@senpi/runtime 3.0.148 → 3.0.150

package/dist/quant/engine/quantdesk/strategy_read.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""What the trader has actually been doing — a strategy fingerprint with receipts, plus a rule-based
+critique. Everything here is computed; the agent turns it into the two-paragraph read."""
+# Copyright 2026 Senpi (https://senpi.ai) — Apache-2.0
+import collections
+import math
+import statistics
+
+import taxonomy
+
+H = 3_600_000.0
+
+
+def _pf(eps):
+    w = sum(e["realized"] for e in eps if e["realized"] > 0); l = -sum(e["realized"] for e in eps if e["realized"] <= 0)
+    return (w / l) if l else (float("inf") if w else None)
+
+
+def by_class_side(closed, majors, large):
+    g = collections.defaultdict(list)
+    for e in closed:
+        g[(taxonomy.classify(e["coin"], majors, large), e["direction"])].append(e)
+    tot = sum(len(v) for v in g.values()) or 1
+    total_real = sum(e["realized"] for v in g.values() for e in v)
+    rows = []
+    for (cls, side), eps in g.items():
+        real = sum(e["realized"] for e in eps)
+        # Ties on realized P&L (two break-even coins, say) break by name. Without it the order fell
+        # through to set iteration, which follows PYTHONHASHSEED: the same book printed its coins in a
+        # different order run to run, and the recorded oracle could not be reproduced reliably.
+        rows.append(dict(cls=cls, label=taxonomy.label(cls), side=side, trades=len(eps), share=len(eps) / tot, realized=real,
+                         pnl_share=(real / total_real) if total_real else None, wins=sum(1 for e in eps if e["win"]), pf=_pf(eps),
+                         coins=sorted({e["coin"] for e in eps}, key=lambda c: (-sum(x["realized"] for x in eps if x["coin"] == c), c))[:4]))
+    rows.sort(key=lambda r: -r["trades"])
+    return rows
+
+
+def simultaneity(closed, opened, window_start, now):
+    """Share of the window with a long AND a short open at once, and the class pairs that overlapped."""
+    intervals = [(e["open_time"], e["close_time"] or now, e["direction"], e["coin"]) for e in closed + opened]
+    if not intervals:
+        return dict(both_share=0.0, pairs=[])
+    pts = sorted({max(window_start, o) for o, _, _, _ in intervals} | {min(now, c) for _, c, _, _ in intervals} | {window_start, now})
+    both = 0.0; pairs = collections.Counter()
+    for a, b in zip(pts, pts[1:]):
+        mid = (a + b) / 2
+        live = [(d, c) for o, cl, d, c in intervals if o <= mid < cl]
+        longs = {c for d, c in live if d == "LONG"}; shorts = {c for d, c in live if d == "SHORT"}
+        if longs and shorts:
+            both += b - a
+            pairs[(tuple(sorted(longs))[:3], tuple(sorted(shorts))[:3])] += b - a
+    span = max(1.0, now - window_start)
+    top = [dict(longs=list(l), shorts=list(s), share=v / span) for (l, s), v in pairs.most_common(2)]
+    return dict(both_share=both / span, pairs=top)
+
+
+def leg_correlation(candles, long_coins, short_coins):
+    """Correlation of hourly returns between the long-leg basket and the short-leg basket the trader
+    actually used. A hedge that moves with its own book is not a hedge."""
+    def basket(coins):
+        series = []
+        for c in coins:
+            cd = candles.get(c)
+            if cd and len(cd[1]) > 200:
+                rows = cd[1]
+                series.append({r[0]: r[4] for r in rows})
+        if not series:
+            return None
+        times = sorted(set.intersection(*(set(s) for s in series)))
+        if len(times) < 100:
+            return None
+        rets = []
+        for a, b in zip(times, times[1:]):
+            rets.append(statistics.mean(math.log(s[b] / s[a]) for s in series if s[a] > 0 and s[b] > 0))
+        return dict(zip(times[1:], rets))
+    L, S = basket(long_coins), basket(short_coins)
+    if not L or not S:
+        return None
+    common = sorted(set(L) & set(S))
+    if len(common) < 100:
+        return None
+    x = [L[t] for t in common]; y = [S[t] for t in common]
+    mx, my = statistics.mean(x), statistics.mean(y)
+    sx, sy = statistics.pstdev(x), statistics.pstdev(y)
+    if not sx or not sy:
+        return None
+    return sum((a - mx) * (b - my) for a, b in zip(x, y)) / (len(x) * sx * sy)
+
+
+def pnl_beta(pnl_curve, btc_candles, account_value, equity=None):
+    """How much of the P&L is just BTC: correlation and beta of P&L changes (as % of equity) to BTC returns
+    over matching intervals."""
+    if not pnl_curve or not btc_candles or len(pnl_curve) < 12 or not account_value:
+        return None
+    times, rows = btc_candles
+    import bisect
+    def px(t):
+        i = bisect.bisect_right(times, t) - 1
+        return rows[i][4] if i >= 0 else None
+    # Every step's P&L used to be divided by TODAY's account value, so a book that doubled over the
+    # window had its early returns scaled by a denominator that did not exist yet — correlation
+    # survives a constant rescale, beta does not. Divide each step by the equity AT THAT STEP, from
+    # the transfer-adjusted curve, so a deposit does not read as a return either.
+    # (@danielmbirochi, #718, round 2.)
+    eq = dict(equity or [])
+    eq_t = sorted(eq)
+    # A step measured against a near-zero equity is a division by the tail, not a return: it reported
+    # "a 1% BTC move swings your equity by about 35%" on a book whose equity collapsed mid-window.
+    # Floor the denominator at a tenth of the window's median equity and drop the steps below it.
+    _pos = [v for v in eq.values() if v and v > 0]
+    _floor = 0.1 * statistics.median(_pos) if _pos else 0.0
+    def eq_at(t):
+        i = bisect.bisect_right(eq_t, t) - 1
+        v = eq[eq_t[i]] if i >= 0 else None
+        return v if v and v > _floor else None
+    xs, ys = [], []
+    for (t0, v0), (t1, v1) in zip(pnl_curve, pnl_curve[1:]):
+        p0, p1 = px(t0), px(t1)
+        base = eq_at(t0) if eq else account_value
+        if p0 and p1 and t1 > t0 and base:
+            xs.append(p1 / p0 - 1); ys.append((v1 - v0) / base)
+    if len(xs) < 10:
+        return None
+    mx, my = statistics.mean(xs), statistics.mean(ys); sx, sy = statistics.pstdev(xs), statistics.pstdev(ys)
+    if not sx or not sy:
+        return None
+    cov = sum((a - mx) * (b - my) for a, b in zip(xs, ys)) / len(xs)
+    return dict(corr=cov / (sx * sy), beta=cov / (sx * sx), n=len(xs))
+
+
+def fingerprint(closed, opened, book, tr, act, tm, candles, ctxs, pnl_curve, window_start, now, equity=None):
+    majors, large = taxonomy.crypto_tiers(ctxs)
+    rows = by_class_side(closed, majors, large)
+    live = [dict(coin=p["coin"], side=p["side"], cls=taxonomy.classify(p["coin"], majors, large), notional=p["notional"]) for p in book["positions"]]
+    # where the MONEY went, closed and open together, by notional — the count-based table can hide a book of held shorts
+    money = collections.defaultdict(float)
+    for e in closed:
+        money[(taxonomy.label(taxonomy.classify(e["coin"], majors, large)), e["direction"], "closed")] += e["peak_notional"]
+    for p in live:
+        money[(taxonomy.label(p["cls"]), p["side"], "open")] += p["notional"]
+    tot_money = sum(money.values()) or 1.0
+    money_rows = sorted((dict(cls=k[0], side=k[1], state=k[2], share=v / tot_money) for k, v in money.items()), key=lambda r: -r["share"])
+    gross = sum(p["notional"] for p in live) or 1.0
+    live_cls = collections.defaultdict(float)
+    for p in live:
+        live_cls[(taxonomy.label(p["cls"]), p["side"])] += p["notional"] / gross
+    net_ratio = abs(book["net_exposure"]) / gross if book["positions"] else None
+    sim = simultaneity(closed, opened, window_start, now)
+    long_coins = {e["coin"] for e in closed if e["direction"] == "LONG"}; short_coins = {e["coin"] for e in closed if e["direction"] == "SHORT"}
+    corr = leg_correlation(candles, long_coins, short_coins) if (long_coins and short_coins) else None
+    beta = pnl_beta(pnl_curve, candles.get("BTC"), book.get("account_value"), equity)
+    # outcome concentration
+    reals = sorted((e["realized"] for e in closed), reverse=True); total = sum(reals)
+    top3 = sum(reals[:3]) if reals else 0.0
+    conc = (top3 / total) if total > 0 else None
+    # sides that never worked
+    dead = [r for r in rows if r["trades"] >= 3 and r["wins"] == 0]
+    coins_traded = len({e["coin"] for e in closed})
+    top_coins = sorted(collections.Counter(e["coin"] for e in closed).items(), key=lambda kv: -kv[1])[:3]
+    hold = tr.get("hold_winners_h") if tr.get("hold_winners_h") is not None else None
+    style = []
+    es = entry_style(tm, tr)
+    if es:
+        style.append(es)
+    if tr.get("adds_per_trade") is not None and tr["adds_per_trade"] >= 1:
+        style.append(f"pyramids — {tr['adds_per_trade']:.1f} added orders per trade on average")
+    if (act.get("twap_share") or 0) > 0.2:   # present-and-None on a book with no TWAPs
+        style.append(f"works orders — {100 * act['twap_share']:.0f}% of fills are TWAP slices")
+    tpd = (tr.get("trades") or 0) / max(1, act.get("active_days") or 1)
+    return dict(class_side=rows, live=live, money=money_rows[:4], open_shorts=sum(1 for p in live if p["side"] == "SHORT"), open_longs=sum(1 for p in live if p["side"] == "LONG"),
+                live_mix=[dict(cls=k[0], side=k[1], share=v) for k, v in sorted(live_cls.items(), key=lambda kv: -kv[1])],
+                net_over_gross=net_ratio, simultaneity=sim, leg_correlation=corr, pnl_beta=beta, outcome_concentration=conc,
+                dead_sides=dead, coins_traded=coins_traded, top_coins=top_coins, trades_per_active_day=tpd, style=style,
+                long_share=tr.get("long_share"))
+
+
+def entry_style(tm, tr):
+    """Chaser or fader, in the words of the side the trader actually trades: a short seller does not "buy weakness"."""
+    if not tm:
+        return None
+    ls = tr.get("long_share")
+    lean = "long" if ls is None or ls >= 0.7 else ("short" if ls <= 0.3 else "mixed")
+    if (tm.get("chased_share") or 0) >= 0.5:
+        return {"long": "buys strength — half or more of your entries come after a ≥3% move up, a chaser",
+                "short": "sells weakness — half or more of your shorts come after a ≥3% drop, a chaser",
+                "mixed": "chases the move — half or more of your entries come after a ≥3% move in their direction"}[lean]
+    if tm.get("pre24_median") is not None and tm["pre24_median"] < -0.02:
+        return {"long": "buys weakness — you enter after the move against you, a fader",
+                "short": "sells strength — you short after the move against you, a fader",
+                "mixed": "fades the move — you enter after the move against you, on both sides"}[lean]
+    return None
+
+
+def statements(fp, tr, book):
+    """The receipts, as sentences the agent can quote. Ordered: what you do → where the money is → what's off."""
+    s = []
+    rows = fp["class_side"]
+    money = fp.get("money") or []
+    if money and money[0]["share"] >= 0.5:
+        m = money[0]
+        s.append(f"by notional, {100 * m['share']:.0f}% of your activity is {m['cls']} {m['side'].lower()}s" + (" you are still holding" if m["state"] == "open" else " you have closed"))
+    if rows:
+        head = rows[0]
+        n_short = sum(r["trades"] for r in rows if r["side"] == "SHORT"); n_all = sum(r["trades"] for r in rows)
+        if n_short == 0 and not fp.get("open_shorts"):
+            tail = "you never short"
+        elif n_short == 0 and fp.get("open_shorts"):
+            tail = f"every closed trade was a long, but the open book is {fp['open_shorts']} short{'s' if fp['open_shorts'] != 1 else ''}"
+        elif n_short / n_all < 0.1:
+            tail = f"you almost never short ({n_short} of {n_all})"
+        else:
+            tail = "your shorts are " + ", ".join(dict.fromkeys(r["label"] for r in rows if r["side"] == "SHORT"))
+        s.append(f"{100 * head['share']:.0f}% of your closed trades are {head['label']} {head['side'].lower()}s ({', '.join(head['coins'][:3])}); {tail}")
+    sim = fp["simultaneity"]
+    if sim["both_share"] >= 0.3 and sim["pairs"]:
+        p = sim["pairs"][0]
+        s.append(f"{100 * sim['both_share']:.0f}% of the window you held longs and shorts at once — typically long {', '.join(p['longs'][:3])} against short {', '.join(p['shorts'][:3])}")
+    if fp["net_over_gross"] is not None and book["positions"]:
+        s.append("the book right now is " + ("directional" if fp["net_over_gross"] > 0.7 else ("hedged" if fp["net_over_gross"] < 0.3 else "tilted"))
+                 + f" — net {100 * fp['net_over_gross']:.0f}% of gross; " + ", ".join(f"{100 * m['share']:.0f}% {m['side'].lower()} {m['cls']}" for m in fp["live_mix"][:3]))
+    if fp["leg_correlation"] is not None and sim["both_share"] >= 0.2:
+        c = fp["leg_correlation"]
+        # Past tense, always. This measures the WINDOW, and it used to sit in the present tense
+        # directly beneath "the book right now is directional — net 100% of gross", so a reader was
+        # told about a long leg the live book does not have. Say when the legs are gone.
+        sides = {q["side"] for q in (book["positions"] or [])}
+        gone = " — though the book you hold now is " + ("short only" if sides == {"SHORT"} else "long only") \
+               if len(sides) == 1 else ""
+        s.append(f"over the window your long leg and your short leg moved together (ρ = {c:+.2f}) — "
+                 + ("the hedge was mostly a fee" if c > 0.6
+                    else ("the legs were genuinely different bets" if c < 0.3 else "partly a hedge"))
+                 + gone)
+    if fp["pnl_beta"]:
+        b = fp["pnl_beta"]
+        if abs(b["corr"]) >= 0.5:
+            rel = "tracks BTC" if b["corr"] > 0 else "is inverse BTC"
+            s.append(f"your P&L {rel} (correlation {b['corr']:+.2f}): a 1% BTC move swings your equity by about {abs(b['beta']):.1f}% — a lot of the result is the market and the leverage, not the picks")
+        else:
+            s.append(f"your P&L is largely independent of BTC (correlation {b['corr']:+.2f}) — the picks, not the tape, drive it")
+    if fp["outcome_concentration"] is not None and fp["outcome_concentration"] >= 0.6 and (tr.get("trades") or 0) >= 10:
+        c = fp["outcome_concentration"]
+        s.append((f"your three best trades are more than all of your realized P&L ({100 * c:.0f}%) — everything else nets negative" if c > 1
+                  else f"your three best trades are {100 * c:.0f}% of your realized P&L") + " — the edge is concentrated, and fragile")
+    for d in fp["dead_sides"][:2]:
+        s.append(f"{d['label']} {d['side'].lower()}s have never paid: 0 of {d['trades']} ({'-' if d['realized'] < 0 else ''}${abs(d['realized']):,.0f})")
+    if fp["coins_traded"] >= 20 and rows:
+        top = fp["top_coins"]
+        s.append(f"you touched {fp['coins_traded']} coins, but " + ", ".join(f"{c} ({n})" for c, n in top) + " are most of the activity")
+    s += fp["style"]
+    return s
+
+
+def critique(fp, tr, book, mf, sm, cohorts=None):
+    """Rule-based: what this way of trading needs to work, and where the data says it isn't getting it."""
+    out = []
+    by = {c["name"]: c for c in (cohorts or [])}
+    pv, ht = by.get("proven"), by.get("hot")
+    if pv and ht and pv.get("agreement") is not None and ht.get("agreement") is not None and pv["agreement"] >= 0.5 and ht["agreement"] <= -0.5:
+        ag, n_rows = list(ht["against"]), len(ht["rows"])
+        cover = {p["coin"]: p.get("stop_covered_share", 1.0) for p in book["positions"]}
+        thin = [x for x in ag if (cover.get(x) or 0.0) < 1.0]      # the squeeze line only says "without stops" when that is true
+        tail = (f"without a full stop on {', '.join(thin)} the day it doesn't is the whole book." if thin else "the stops are what make the day it doesn't survivable.")
+        if len(ag) * 2 >= max(1, n_rows):
+            out.append(f"You are positioned with the record and against the momentum: the proven cohort sits with you, the last 30 days' winners are on the other side on {len(ag)} of {n_rows} coins. That is the shape of a squeeze — it pays until it doesn't, and {tail}")
+        elif ag:
+            out.append(f"On {', '.join(ag)} you sit with the proven cohort and against the last 30 days' winners. That is the shape of a squeeze on {'that coin' if len(ag) == 1 else 'those coins'} — it pays until it doesn't, and {tail}")
+    elif pv and ht and pv.get("agreement") is not None and ht.get("agreement") is not None and pv["agreement"] <= -0.5 and ht["agreement"] >= 0.5:
+        out.append(f"You are riding the momentum against the record: the hot cohort is with you, the proven cohort is on the other side on {len(pv['against'])} of {len(pv['rows'])} coins. Momentum books need the exit decided in advance.")
+    sim = fp["simultaneity"]; corr = fp["leg_correlation"]
+    if sim["both_share"] >= 0.3 and corr is not None and corr > 0.6:
+        out.append("A long/short book only earns its funding and fees if the legs diverge. Yours are correlated — you are paying two spreads for one bet. Either pick the side or hedge with something that actually moves differently.")
+    if fp["net_over_gross"] is not None and fp["net_over_gross"] > 0.7 and mf and mf.get("against", 0):
+        ag_coins = [x["coin"] for x in mf.get("rows") or [] if str(x.get("fit", "")).startswith("AGAINST")]
+        gross = sum(p.get("notional", 0.0) for p in book["positions"]) or 1.0
+        share = sum(p.get("notional", 0.0) for p in book["positions"] if p["coin"] in ag_coins) / gross
+        if share >= 0.5:
+            out.append(f"A directional book lives or dies with the tape, and most of it ({100 * share:.0f}% by notional) is against the trend right now. Directional needs a regime filter; you are running it without one.")
+        elif share >= 0.2:
+            out.append(f"A directional book lives or dies with the tape, and {100 * share:.0f}% of it by notional ({', '.join(ag_coins)}) is against the trend right now. Directional needs a regime filter; you are running it without one.")
+    if fp["pnl_beta"] and fp["pnl_beta"]["corr"] >= 0.6:
+        out.append("If the P&L is mostly BTC, the leverage and the fees are the only things you are adding. Either the picks need to diverge from BTC, or the same exposure is cheaper with one position and a stop.")
+    if fp["outcome_concentration"] is not None and fp["outcome_concentration"] >= 0.6 and (tr.get("trades") or 0) >= 10:
+        out.append("An edge that lives in three trades is a story, not a system. The question your record asks is whether the process that found those three is repeatable — the size-vs-outcome and hold-time tables say where.")
+    for d in fp["dead_sides"][:1]:
+        out.append(f"Stop trading {d['label']} {d['side'].lower()}s until you can say what would make one work; the sample says nothing has.")
+    if tr.get("hold_ratio") and tr["hold_ratio"] > 2:
+        out.append("The strategy's exits are asymmetric the wrong way: losers get time, winners don't. That is the single most expensive habit in the record.")
+    if sm and sm.get("against") and not (pv and ht):
+        out.append(f"On {', '.join(sm['against'])} you are on the other side of the proven cohort. Being contrarian is a strategy only if it is deliberate — is it?")
+    if not out:
+        out.append("The structure is coherent: the book does what the record says it does. The improvements are in execution and risk, not in the thesis.")
+    return out

package/dist/quant/engine/quantdesk/taxonomy.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Asset classes for the strategy read. Crypto tiers come from LIVE open interest (majors = top 3 by OI,
+large caps = the next 12, alts = the rest); memecoins are the 1000×-denominated `k…` names plus a short,
+documented list; xyz groups are senpi-market-pulse's own (verbatim), so the two skills agree."""
+# Copyright 2026 Senpi (https://senpi.ai) — Apache-2.0
+XYZ_GROUPS = {
+    "semis_memory":   ["MU", "SNDK", "SKHX", "DRAM", "WDC"],
+    "semis_equipment": ["ASML", "TSM", "QCOM", "ARM", "MRVL"],
+    "semis_logic":    ["NVDA", "AMD", "AVGO", "SMH"],
+    "software_megacap": ["AMZN", "MSFT", "META", "GOOGL", "AAPL", "ORCL", "PLTR"],
+    "crypto_proxy":   ["MSTR", "COIN", "HOOD", "CRWV"],
+    "other_equity":   ["TSLA", "SPCX", "ZHIPU"],
+    "indices":        ["SP500", "XYZ100", "JP225", "KR200", "NIFTY", "VIX"],
+    "commodities":    ["GOLD", "SILVER", "COPPER", "BRENTOIL", "NATGAS", "PLATINUM"],
+    "macro_fx":       ["DXY", "JPY", "EUR", "GBP"],
+}
+XYZ_CLASS = {}
+for _g, _names in XYZ_GROUPS.items():
+    for _n in _names:
+        XYZ_CLASS[_n] = ("xyz_" + ("equities" if _g in ("semis_memory", "semis_equipment", "semis_logic", "software_megacap", "crypto_proxy", "other_equity")
+                                   else _g))
+# memecoins beyond the k-prefix rule — a taxonomy list, never a trading whitelist
+MEMES = {"DOGE", "WIF", "FARTCOIN", "PUMP", "TRUMP", "MOODENG", "POPCAT", "PNUT", "PEPE", "SHIB", "BONK", "FLOKI", "GOAT", "CHILLGUY",
+         "MEW", "BRETT", "TURBO", "NEIRO", "SPX", "CASHCAT", "PONS", "MELANIA", "AI16Z", "VVV", "GRIFFAIN"}
+LABELS = {"majors": "majors", "large_caps": "large caps", "alts": "alts", "memes": "memecoins", "xyz_equities": "equities", "xyz_indices": "indices",
+          "xyz_commodities": "commodities", "xyz_macro_fx": "FX / macro", "xyz_other": "other xyz"}
+
+
+def crypto_tiers(ctxs):
+    """(majors, large_caps) from the main-dex contexts, by open interest in USD."""
+    rows = []
+    for u, c in zip(ctxs[0]["universe"], ctxs[1]):
+        try:
+            rows.append((float(c["openInterest"]) * float(c["markPx"]), u["name"]))
+        except (TypeError, ValueError, KeyError):
+            continue
+    rows.sort(reverse=True)
+    names = [n for _, n in rows]
+    return set(names[:3]), set(names[3:15])
+
+
+def classify(coin, majors, large):
+    if coin.startswith("xyz:"):
+        return XYZ_CLASS.get(coin[4:], "xyz_other")
+    if coin in majors:
+        return "majors"
+    if coin.startswith("k") and coin[1:2].isupper() or coin in MEMES:
+        return "memes"
+    if coin in large:
+        return "large_caps"
+    return "alts"
+
+
+def label(cls):
+    return LABELS.get(cls, cls)

package/dist/quant/engine/quantdesk/timing.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Candle-based timing analyses per complete round trip: the move before entry (chasing), favourable and
+adverse excursions, give-back of peak gains, and counterfactuals that are only ever surfaced when they
+are positive across a small fixed grid (never a fitted parameter). Dollar figures use peak size × price
+move — an approximation that ignores adds and partials, and is labelled as such."""
+# Copyright 2026 Senpi (https://senpi.ai) — Apache-2.0
+import bisect
+import statistics
+
+H = 3_600_000.0
+CUT_GRID_H = (12.0, 24.0, 48.0)                 # time-cut on losers
+LOCK_GRID = ((0.03, 0.5), (0.05, 0.5), (0.05, 0.3))  # (arm at +peak%, lock this share of the peak)
+CHASE_PCT = 0.03                                 # an entry after a ≥3% move in its direction over 24h
+
+
+def load_candles(raw):
+    out = {}
+    for coin, rows in (raw or {}).items():
+        if rows:
+            out[coin] = ([r[0] for r in rows], rows)
+    return out
+
+
+def px_at(c, t):
+    times, rows = c
+    i = bisect.bisect_right(times, t) - 1
+    return rows[i][4] if i >= 0 else None
+
+
+def path(c, t0, t1):
+    times, rows = c
+    return rows[bisect.bisect_left(times, t0):bisect.bisect_right(times, t1)]
+
+
+def _fav(r, sgn, ent):
+    return sgn * ((r[2] if sgn > 0 else r[3]) / ent - 1)
+
+
+def _adv(r, sgn, ent):
+    return sgn * ((r[3] if sgn > 0 else r[2]) / ent - 1)
+
+
+def _at(path, times, t, p):
+    """What the trade would show if the WHOLE position were closed at time `t`, price `p`: the P&L
+    already booked by then, plus mark-to-market on the size actually open at that moment against its
+    average entry.
+
+    The old form was `return x peak_size x entry_vwap` — it priced the PEAK size as if it had been
+    held from entry through to `t`. On a position scaled in and out those are not the same trade and
+    the error scales with the notional: xyz:SKHX ran 507 fills with $16.3M entered against a $7.1M
+    peak and its 48h cut came back at +$96,858 against a $44,302 loss, 2.2x the thing it was
+    "fixing". Three of four losing books were offered a recovery larger than their entire loss.
+    Pricing on the exposure that existed removes the assumption rather than bounding its damage.
+    (B6, @0xsarvesh #718.)"""
+    i = bisect.bisect_right(times, t) - 1
+    if i < 0:
+        return None
+    _, size, avg, booked = path[i]
+    if avg is None:
+        return None
+    return booked + size * (p - avg)
+
+
+def per_trade(episodes, candles):
+    out = []
+    for e in episodes:
+        c = candles.get(e["coin"]); ent = e["entry_vwap"]
+        if not c or not ent or not e.get("complete"):
+            continue
+        sgn = 1 if e["direction"] == "LONG" else -1
+        p24 = px_at(c, e["open_time"] - 24 * H)
+        pre24 = sgn * (ent / p24 - 1) if p24 else None
+        rows = [r for r in path(c, e["open_time"] - H, e["close_time"]) if r[0] >= e["open_time"] - H]
+        ntl = e["peak_size"] * ent
+        # There IS per-moment exposure in this data — `size_path` carries it — so the exit grid no
+        # longer has to assume the peak size was held throughout, and no longer has to decline the
+        # positions where that assumption fails worst. The `cycled` skip this replaces was the right
+        # call while the counterfactual was constant-size; it dropped 10 of 11 rows on one of the
+        # books in the report, which is its own kind of wrong. (B6, @0xsarvesh #718.)
+        # senpi's indexed rows are aggregate positions, not fills: one size, one entry price, no
+        # intra-trade path — and for those the constant-size form was always exactly right
+        # (`entry_val == peak_notional`, so they never tripped the old `cycled` skip either). The
+        # degenerate one-step path below reproduces the old arithmetic for them to the cent, so this
+        # change lands only where there IS a path to be wrong about.
+        spath = e.get("size_path") or [(e["open_time"], sgn * e["peak_size"], ent, 0.0)]
+        stimes = [x[0] for x in spath]
+        mfe = mae = 0.0
+        cut_px = {h: None for h in CUT_GRID_H}
+        for r in rows:
+            mfe = max(mfe, _fav(r, sgn, ent)); mae = min(mae, _adv(r, sgn, ent))
+            for h in CUT_GRID_H:
+                if cut_px[h] is None and r[0] >= e["open_time"] + h * H:
+                    cut_px[h] = (r[0], r[4])
+        realized_pct = e["realized"] / ntl if ntl else 0.0
+        give_back = ((mfe - realized_pct) / mfe) if (mfe > 0 and realized_pct < mfe) else 0.0
+        locks = {}
+        for arm, share in LOCK_GRID:
+            locks[f"{arm:.2f}/{share:.1f}"] = _lock_cf(rows, e, sgn, ent, spath, stimes, mfe, arm, share)
+        cuts = {}
+        for h in CUT_GRID_H:
+            hit = cut_px[h]
+            # every trade still open at hour h, winner or loser. Charging a time-cut only on the
+            # losers is survivorship bias — at hour h you do not yet know which is which — and it
+            # inflated the cut counterfactual to more than the book's whole equity.
+            v = _at(spath, stimes, hit[0], hit[1]) if (hit and e["hold_h"] > h) else None
+            cuts[f"{h:.0f}"] = (v - e["realized"]) if v is not None else None
+        out.append(dict(coin=e["coin"], direction=e["direction"], realized=e["realized"], hold_h=e["hold_h"], win=e["win"], pre24=pre24,
+                        chased=(pre24 is not None and pre24 >= CHASE_PCT), mfe=mfe, mae=mae, realized_pct=realized_pct, give_back=give_back,
+                        notional=ntl, lock_cf=locks, cut_cf=cuts, open_time=e["open_time"]))
+    return out
+
+
+def _lock_cf(rows, e, sgn, ent, spath, stimes, mfe, arm, share):
+    """Exit when price gives back (1-share) of the peak gain, once the peak reached `arm`. Returns the
+    dollar difference vs what was realized, or None when the rule never engaged.
+
+    The RULE is unchanged — a fixed grid measured against the entry VWAP, never fitted. What changed
+    is the pricing of the exit it produces: the stop fills the position that exists at that moment,
+    not the peak size assumed held since entry."""
+    if mfe < arm:
+        return None
+    armed, lvl = False, None
+    for r in rows:
+        if r[0] < e["open_time"]:
+            continue
+        fav = _fav(r, sgn, ent)
+        if fav >= arm:
+            armed = True
+        if armed:
+            lvl = max(lvl or 0.0, fav * share)
+            if _adv(r, sgn, ent) <= lvl:
+                v = _at(spath, stimes, r[0], ent * (1 + sgn * lvl))
+                return None if v is None else v - e["realized"]
+    return None
+
+
+def summarize(rows):
+    med = lambda xs: statistics.median(xs) if xs else None  # noqa: E731
+    wins = [r for r in rows if r["win"]]; losses = [r for r in rows if not r["win"]]
+    chased = [r for r in rows if r["chased"]]; calm = [r for r in rows if r["pre24"] is not None and not r["chased"]]
+    def pf(rs):
+        w = sum(r["realized"] for r in rs if r["realized"] > 0); l = -sum(r["realized"] for r in rs if r["realized"] <= 0)
+        return (w / l) if l else (None if not w else float("inf"))
+    cuts = {h: [r["cut_cf"][h] for r in rows if r["cut_cf"][h] is not None] for h in (f"{x:.0f}" for x in CUT_GRID_H)}
+    locks = {k: [r["lock_cf"][k] for r in rows if r["lock_cf"][k] is not None] for k in rows[0]["lock_cf"]} if rows else {}
+    return dict(n=len(rows),
+                pre24_median=med([r["pre24"] for r in rows if r["pre24"] is not None]),
+                chased_share=(len(chased) / len([r for r in rows if r["pre24"] is not None])) if rows and any(r["pre24"] is not None for r in rows) else None,
+                chased_n=len(chased), chased_realized=sum(r["realized"] for r in chased), chased_pf=pf(chased), calm_pf=pf(calm),
+                mfe_median_winners=med([r["mfe"] for r in wins]), give_back_median=med([r["give_back"] for r in wins if r["mfe"] > 0]),
+                mae_median_losers=med([r["mae"] for r in losses]),
+                losers_that_were_green=(sum(1 for r in losses if r["mfe"] >= 0.01) / len(losses)) if losses else None,
+                cut=_grid(cuts), lock=_grid(locks))
+
+
+def _grid(d):
+    """Per setting: total $ and count; plus `robust` = the median setting's total when ≥ 2 of the settings are
+    positive — the only number the desk is allowed to call a leak."""
+    per = {k: dict(total=sum(v), n=len(v)) for k, v in d.items()}
+    totals = sorted(x["total"] for x in per.values() if x["n"])
+    robust = None
+    if len(totals) >= 2 and sum(1 for t in totals if t > 0) >= 2:
+        robust = statistics.median(totals)
+    return dict(settings=per, robust=robust)

package/dist/quant/engine/quantdesk/voice.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Second person is for the trader's own book. For someone else's wallet the desk speaks in the third
+person — English second person and third person plural share every verb form, so the switch is a
+pronoun rewrite. The product persona ("your quant") stays addressed to the reader, who hired it."""
+# Copyright 2026 Senpi (https://senpi.ai) — Apache-2.0
+import re
+
+KEEP = ("YOUR QUANT — LIVE", "Your quant", "your quant", "hire my quant", "your own book", "under **your** name", "under your name", "your name",
+        "you could run", "you can run", "you run under", "by the time you see them", "you see them", "Say *hire", "you hired", "you want", "Want me", "Want the",
+        "Want their", "Want to", "your say-so", "on your side", "run for you", "run this for you", "tell you", "your agents")
+# object case first: "paid you", "sits with you", "against you" → them. English second person hides the case; third person does not.
+OBJECT = re.compile(r"\b(against|with|behind|ahead of|beside|from|of|by|to|at|on|for|between|around|near|over|under|toward|towards|without|into|onto|off|past|"
+                    r"paid|pays|paying|pay|cost|costs|costing|tells|tell|telling|told|shows|show|showing|showed|lets|let|letting|gives|give|gave|giving|"
+                    r"hurt|hurts|hurting|keeps|keep|kept|keeping|puts|put|putting|leaves|leave|left|leaving|makes|make|made|making|gets|get|got|getting|"
+                    r"beat|beats|beating|saves|save|saved|saving|earns|earn|earned|earning|owes|owe|owed|protects|protect|protected|protecting|"
+                    r"stops|stop|stopped|stopping|warns|warn|warned|reminds|remind|reminded) you\b")
+PAIRS = (
+    (r"\bYou're\b", "They're"), (r"\byou're\b", "they're"), (r"\bYou've\b", "They've"), (r"\byou've\b", "they've"),
+    (r"\bYou'd\b", "They'd"), (r"\byou'd\b", "they'd"), (r"\bYou'll\b", "They'll"), (r"\byou'll\b", "they'll"),
+    (r"\bYourself\b", "Themselves"), (r"\byourself\b", "themselves"), (r"\bYours\b", "Theirs"), (r"\byours\b", "theirs"),
+    (r"\bYour\b", "Their"), (r"\byour\b", "their"), (r"\bYou\b", "They"), (r"\byou\b", "they"),
+)
+
+
+def third_person(md, short_addr=None):
+    keep = {}
+    for i, k in enumerate(KEEP):
+        tok = f"\x00{i}\x00"
+        keep[tok] = k
+        md = md.replace(k, tok)
+    md = OBJECT.sub(r"\1 them", md)
+    for pat, rep in PAIRS:
+        md = re.sub(pat, rep, md)
+    for tok, k in keep.items():
+        md = md.replace(tok, k)
+    if short_addr:
+        md = md.replace(f"# Their desk — `{short_addr}`", f"# The desk for `{short_addr}`")
+    md = md.replace("| Coin | They | Cohort | Read |", "| Coin | Trader | Cohort | Read |").replace("| Coin | They | Smart money | Read |", "| Coin | Trader | Smart money | Read |")
+    md = re.sub(r"(?m)^They: ", "This trader: ", md)
+    md = md.replace("They vs smart money", f"`{short_addr}` vs smart money" if short_addr else "This trader vs smart money")
+    md = md.replace("What they've been doing", "What they've been doing").replace("The market they're trading in", "The market they're trading in")
+    return md