stockproof 0.3.0__py3-none-any.whl

stockproof/__init__.py

@@ -0,0 +1,15 @@
+"""stockproof (有据): an LLM reads stock news, earnings and filings with cited sources, and history checks what matters."""
+
+import os as _os
+
+__version__ = "0.3.0"
+
+
+def compat_env() -> None:
+    """The project was called marketmood until 0.2: keep reading the old MARKETMOOD_* variables."""
+    for k, v in list(_os.environ.items()):
+        if k.startswith("MARKETMOOD_"):
+            _os.environ.setdefault("STOCKPROOF_" + k[len("MARKETMOOD_"):], v)
+
+
+compat_env()

stockproof/__main__.py

@@ -0,0 +1,5 @@
+"""Allows `python3 -m stockproof ...` without installing."""
+from stockproof.cli import main
+
+if __name__ == "__main__":
+    main()

stockproof/announcements.py

@@ -0,0 +1,263 @@
+"""
+Announcement monitor (A-shares and Hong Kong, via Eastmoney).
+
+Company announcements are the most important information source in A-shares, and their titles
+are highly standardized ("关于股东减持股份计划的公告", "关于收到上海证券交易所问询函的公告"…).
+So the type and importance come from title rules: free, instant and predictable. The LLM is only
+used for the important ones: a two-sentence summary and an impact score, read from the full text.
+
+Categories carry a typical direction (+1 usually good for the price, -1 usually bad, 0 unclear);
+the LLM's score for the specific announcement can differ (e.g. a small buyback plan).
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import re
+
+from stockproof import clock
+from stockproof import cn
+
+# (key, importance 3/2/1, typical direction, title patterns). First match wins, so order matters:
+# specific risks before generic words ("终止回购" is not a buyback).
+RULES = [
+    ("delisting_risk", 3, -1, [r"退市", r"\*ST", r"终止上市", r"暂停上市", r"实施其他风险警示", r"delisting"]),
+    ("investigation", 3, -1, [r"立案", r"行政处罚", r"刑事", r"留置", r"被调查", r"investigation"]),
+    ("regulatory_letter", 3, -1, [r"问询函", r"关注函", r"监管函", r"警示函", r"监管措施", r"纪律处分", r"通报批评"]),
+    ("trading_halt", 3, 0, [r"停牌", r"trading halt", r"suspension of trading"]),
+    ("restructuring", 3, 0, [r"重大资产重组", r"重大资产", r"吸收合并", r"收购报告书", r"要约收购", r"控制权变更",
+                             r"实际控制人.{0,6}变更", r"major transaction", r"very substantial"]),
+    ("earnings_warning", 3, 0, [r"业绩预告", r"业绩预亏", r"业绩预增", r"业绩快报", r"profit warning",
+                                r"positive profit alert", r"盈利警告", r"盈利预告"]),
+    ("insider_selling", 3, -1, [r"减持", r"大宗交易"]),
+    ("insider_buying", 2, 1, [r"增持"]),
+    ("buyback", 2, 1, [r"(?<!终止)回购.{0,10}(股份|方案|计划|报告书|进展|实施)", r"buy-?back", r"repurchase"]),
+    ("lawsuit", 2, -1, [r"诉讼", r"仲裁", r"litigation"]),
+    ("pledge_freeze", 2, -1, [r"质押", r"冻结", r"司法拍卖"]),
+    ("lockup_expiry", 2, -1, [r"限售股.{0,8}上市流通", r"解除限售", r"解禁"]),
+    ("share_issue", 2, -1, [r"非公开发行", r"向特定对象发行", r"定向增发", r"配股", r"可转换公司债券", r"可转债",
+                            r"placing", r"rights issue", r"subscription of new shares"]),
+    ("management_change", 2, 0, [r"辞职", r"辞任", r"离任", r"resignation", r"change of (director|chief)"]),
+    ("big_contract", 2, 1, [r"中标", r"重大合同", r"战略合作", r"framework agreement"]),
+    ("incentive", 1, 1, [r"股权激励", r"员工持股", r"限制性股票", r"股票期权", r"share award", r"share option"]),
+    ("dividend", 1, 1, [r"利润分配", r"分红", r"派息", r"权益分派", r"dividend"]),
+    ("periodic_report", 1, 0, [r"季度报告", r"半年度报告", r"年度报告", r"interim report", r"annual report",
+                               r"quarterly report", r"results announcement", r"业绩公告"]),
+]
+# Paperwork that only accompanies an event (lawyers' opinions, brokers' checks, replies, meeting
+# resolutions…) or is routine. Checked FIRST: "律师事务所关于…增持股份的法律意见书" is not a purchase.
+NOISE = [r"律师事务所", r"法律意见", r"核查意见", r"专项核查", r"持续督导", r"自查报告", r"的回复", r"之回复",
+         r"论证分析", r"会议规则", r"募集说明书", r"上市保荐", r"保荐书", r"独立董事", r"会议决议", r"董事会决议",
+         r"监事会决议", r"股东(大)?会(决议|通知|的通知|会议资料)", r"召开.{0,30}(股东|说明会|会议)", r"说明会",
+         r"投资者关系", r"章程", r"议事规则", r"管理制度", r"工作细则", r"履职情况", r"内部控制", r"社会责任",
+         r"ESG", r"環境、社會", r"可持续发展", r"更正", r"英文", r"H股公告", r"月报表", r"月報表", r"通函",
+         r"关联交易预计", r"日常关联交易", r"提示性公告$", r"财务顾问", r"董事会关于本次交易", r"验资",
+         r"评级报告", r"可行性分析", r"审核意见", r"前十(大|名)(股东|流通)",
+         r"monthly return", r"next day disclosure", r"date of board meeting", r"董事会会议召开日期"]
+# Words that turn a matching title into something routine.
+NOT_EVENT = {
+    "regulatory_letter": [r"不存在", r"未被", r"审核问询", r"注册.{0,6}问询", r"回复", r"回函"],
+    "trading_halt": [r"债券", r"转债", r"转股", r"票据", r"可交换"],
+    "buyback": [r"限制性股票", r"激励", r"债券", r"注销.{0,6}限制性"],
+    "lockup_expiry": [r"限制性股票", r"激励", r"员工持股"],
+    "investigation": [r"不存在", r"说明会"],
+    "pledge_freeze": [r"解除质押(?!.{0,4}及)"],
+}
+
+CATEGORY_NAMES = {
+    "en": {"delisting_risk": "delisting / ST risk", "investigation": "investigation / penalty",
+           "regulatory_letter": "regulator's letter", "trading_halt": "trading halt", "restructuring": "M&A / restructuring",
+           "earnings_warning": "earnings preview", "insider_selling": "shareholder selling",
+           "insider_buying": "shareholder buying", "buyback": "buyback", "lawsuit": "lawsuit", "pledge_freeze": "pledge / freeze",
+           "lockup_expiry": "lock-up expiry", "share_issue": "new shares / convertible", "management_change": "management change",
+           "big_contract": "major contract", "incentive": "stock incentive", "dividend": "dividend",
+           "periodic_report": "periodic report", "other": "other"},
+    "zh": {"delisting_risk": "退市/ST 风险", "investigation": "立案调查/处罚", "regulatory_letter": "监管问询",
+           "trading_halt": "停牌", "restructuring": "重组/收购", "earnings_warning": "业绩预告/快报",
+           "insider_selling": "股东减持", "insider_buying": "股东增持", "buyback": "回购", "lawsuit": "诉讼仲裁",
+           "pledge_freeze": "质押/冻结", "lockup_expiry": "限售股解禁", "share_issue": "增发/可转债",
+           "management_change": "高管变动", "big_contract": "重大合同/中标", "incentive": "股权激励", "dividend": "分红",
+           "periodic_report": "定期报告", "other": "其他"},
+}
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS announcements (
+    art_code TEXT PRIMARY KEY,
+    ticker TEXT NOT NULL,
+    date TEXT NOT NULL,
+    title TEXT NOT NULL,
+    category TEXT NOT NULL,
+    importance INTEGER NOT NULL,
+    direction INTEGER NOT NULL,
+    url TEXT,
+    first_seen TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_ann_ticker ON announcements (ticker, date);
+CREATE TABLE IF NOT EXISTS announcement_reads (
+    art_code TEXT NOT NULL,
+    model TEXT NOT NULL,
+    lang TEXT NOT NULL,
+    result TEXT NOT NULL,
+    read_at TEXT NOT NULL,
+    PRIMARY KEY (art_code, model, lang)
+);
+"""
+READ_VERSION = 1
+
+
+def classify(title: str) -> tuple[str, int, int]:
+    """(category, importance 0-3, typical direction). Importance 0 = routine paperwork."""
+    t = title.split(":", 1)[-1] if ":" in title[:20] else title       # drop the "公司名:" prefix
+    low = t.lower()
+    hit = lambda pats: any(re.search(p, t) or re.search(p, low, re.I) for p in pats)
+    if hit(NOISE):
+        return "other", 0, 0
+    for key, imp, direction, pats in RULES:
+        if hit(pats) and not hit(NOT_EVENT.get(key, [])):
+            return key, imp, direction
+    if re.search(r"限制性股票|激励", t):
+        return "incentive", 1, 1                  # vesting / cancellation of incentive shares
+    if re.search(r"解除质押", t):
+        return "pledge_freeze", 1, 1              # pledge released: mildly reassuring
+    return "other", 1, 0
+
+
+def page_url(info: dict, art_code: str) -> str:
+    if info["market"] == "HK":
+        return f"https://data.eastmoney.com/notices/hk/detail/{info['code']}/{art_code}.html"
+    return f"https://data.eastmoney.com/notices/detail/{info['code']}/{art_code}.html"
+
+
+def ensure_schema(store) -> None:
+    store.conn.executescript(SCHEMA)
+
+
+def fetch(store, ticker: str, days: int = 30) -> int:
+    """Save the latest announcements of one stock (newest page only). Returns how many were new."""
+    ensure_schema(store)
+    info = cn.parse(ticker)
+    if not info:
+        return 0
+    since = (clock.today() - dt.timedelta(days=days)).isoformat()
+    now = dt.datetime.now().isoformat(timespec="seconds")
+    new = 0
+    for a in cn.announcements(info, page_size=100):
+        if not a.get("art_code") or not a.get("date") or a["date"] < since:
+            continue
+        cat, imp, direction = classify(a["title"])
+        cur = store.conn.execute(
+            "INSERT OR IGNORE INTO announcements VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (a["art_code"], info["symbol"], a["date"], a["title"], cat, imp, direction,
+             page_url(info, a["art_code"]), now))
+        new += cur.rowcount
+    store.conn.commit()
+    return new
+
+
+def build_prompt(name: str, ticker: str, title: str, text: str, lang: str) -> str:
+    language = "Simplified Chinese" if lang == "zh" else "English"
+    return (
+        "You are an equity analyst reading a listed company's official announcement.\n"
+        f"Company: {name} ({ticker}). Title: {title}\n\n"
+        f"--- ANNOUNCEMENT (may be cut off) ---\n{text}\n--- END ---\n\n"
+        "Report only what the announcement says.\n"
+        "Reply ONLY with JSON:\n"
+        f'{{"summary": "at most 2 sentences in {language}, with the key numbers (amounts, share counts, '
+        'percentages, dates)",\n'
+        ' "impact": -1 to 1 (likely effect on the share price; 0 if routine or unclear),\n'
+        f' "why": "one short sentence in {language}"}}'
+    )
+
+
+def read(store, client, model_id: str, art_code: str, name: str, ticker: str, title: str, lang: str) -> dict:
+    """LLM summary of one announcement, cached per model and language."""
+    ensure_schema(store)
+    key = f"{model_id}#a{READ_VERSION}"
+    row = store.conn.execute("SELECT result FROM announcement_reads WHERE art_code=? AND model=? AND lang=?",
+                             (art_code, key, lang)).fetchone()
+    if row:
+        return json.loads(row[0])
+    text, pdf = cn.announcement_text(art_code)
+    data = client.chat_json(build_prompt(name, ticker, title, text[:8000] or title, lang))
+    try:
+        impact = max(-1.0, min(1.0, float(data.get("impact", 0))))
+    except (TypeError, ValueError):
+        impact = 0.0
+    result = {"summary": str(data.get("summary", ""))[:400], "impact": impact,
+              "why": str(data.get("why", ""))[:200], "pdf": pdf}
+    store.conn.execute("INSERT OR REPLACE INTO announcement_reads VALUES (?, ?, ?, ?, ?)",
+                       (art_code, key, lang, json.dumps(result, ensure_ascii=False),
+                        dt.datetime.now().isoformat(timespec="seconds")))
+    store.conn.commit()
+    return result
+
+
+def refresh(store, client, model_id: str, tickers: list[str], names: dict, lang: str,
+            days: int = 30, min_importance: int = 2, max_reads: int = 40, log=print) -> dict:
+    """Fetch announcements for the Chinese tickers; summarize the important new ones with the LLM."""
+    ensure_schema(store)
+    stats = {"stocks": 0, "new": 0, "read": 0, "errors": 0}
+    for tk in tickers:
+        if not cn.is_cn(tk):
+            continue
+        try:
+            stats["new"] += fetch(store, tk, days)
+            stats["stocks"] += 1
+        except cn.Blocked as e:
+            stats["errors"] += 1
+            log(f"  announcements skipped: {e}")
+            return stats                                 # the rest would be refused too
+        except Exception as e:
+            stats["errors"] += 1
+            log(f"  {tk}: announcements unavailable ({type(e).__name__})")
+    if client is None:
+        return stats
+    since = (clock.today() - dt.timedelta(days=days)).isoformat()
+    key = f"{model_id}#a{READ_VERSION}"
+    todo = store.conn.execute(
+        "SELECT a.art_code, a.ticker, a.title FROM announcements a WHERE a.importance >= ? AND a.date >= ? "
+        "AND NOT EXISTS (SELECT 1 FROM announcement_reads r WHERE r.art_code = a.art_code AND r.model = ? "
+        "AND r.lang = ?) ORDER BY a.importance DESC, a.date DESC LIMIT ?",
+        (min_importance, since, key, lang, max_reads)).fetchall()
+    for code, tk, title in todo:
+        try:
+            read(store, client, model_id, code, names.get(tk, tk), tk, title, lang)
+            stats["read"] += 1
+        except Exception as e:
+            from stockproof.core import is_fatal
+            stats["errors"] += 1
+            if is_fatal(e):
+                raise
+            if isinstance(e, cn.Blocked):
+                log(f"  announcement summaries skipped: {e}")
+                break
+    return stats
+
+
+def recent(store, tickers: list[str], days: int = 30, min_importance: int = 1,
+           lang: str = "en", model_id: str | None = None) -> list[dict]:
+    """Saved announcements (newest first) with the LLM summary when there is one. No network."""
+    ensure_schema(store)
+    if not tickers:
+        return []
+    since = (clock.today() - dt.timedelta(days=days)).isoformat()
+    marks = ",".join("?" * len(tickers))
+    rows = store.conn.execute(
+        f"SELECT art_code, ticker, date, title, category, importance, direction, url FROM announcements "
+        f"WHERE ticker IN ({marks}) AND date >= ? AND importance >= ? ORDER BY date DESC, importance DESC",
+        (*tickers, since, min_importance)).fetchall()
+    out = []
+    for code, tk, date, title, cat, imp, direction, url in rows:
+        q = ("SELECT result FROM announcement_reads WHERE art_code = ? AND lang = ? "
+             + ("AND model = ? " if model_id else "") + "ORDER BY read_at DESC LIMIT 1")
+        params = (code, lang, f"{model_id}#a{READ_VERSION}") if model_id else (code, lang)
+        r = store.conn.execute(q, params).fetchone()
+        if r is None:                          # fall back to a reading in the other language
+            r = store.conn.execute("SELECT result FROM announcement_reads WHERE art_code = ? "
+                                   "ORDER BY read_at DESC LIMIT 1", (code,)).fetchone()
+        out.append({"art_code": code, "ticker": tk, "date": date, "title": title, "category": cat,
+                    "category_name": CATEGORY_NAMES.get(lang, CATEGORY_NAMES["en"]).get(cat, cat),
+                    "importance": imp, "direction": direction, "url": url,
+                    "read": json.loads(r[0]) if r else None})
+    return out

stockproof/backtest.py

@@ -0,0 +1,282 @@
+"""
+Can the post-earnings drift be traded? An event-driven backtest with real-world frictions.
+
+Rules (all decided with information available at the time):
+  - Signal: SUE at the announcement. Long the stocks with SUE >= long_sue, (hypothetically)
+    short those with SUE <= short_sue.
+  - Entry: at the close of day 1 (the day after the announcement date), i.e. after the
+    reaction window, so the backtest earns only the drift. If the stock can't be traded that day
+    (suspended, or closed at the limit: limit-up blocks buying, limit-down blocks selling) the
+    order waits up to `max_wait` days, then is dropped.
+  - Exit: at the close `hold` trading days later; if the stock can't be sold then (suspended or
+    limit-down for a long), it waits for the first day it can.
+  - Portfolio: every open position has the same weight; days with no positions are in cash.
+  - Costs, charged on the first and last day of each trade: commission on both sides, stamp duty
+    on sales (China: 0.1%, 0.05% from 2023-08-28), and slippage on both sides.
+  - Benchmark: the equal-weighted average of all stocks in the price file (same universe, so the
+    survivorship of "today's index members" affects both sides alike).
+
+Long-only excess return is the practical number for A-shares (shorting single stocks is limited and
+expensive); the long-short result shows the size of the effect.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class Costs:
+    commission: float = 0.00025       # each side
+    slippage: float = 0.001           # each side: spread + market impact for large caps
+    stamp_duty: float = 0.001         # on sales; China halved it on 2023-08-28
+    stamp_duty_cut: str | None = "2023-08-28"
+    stamp_duty_after: float = 0.0005
+
+    def buy(self, day) -> float:
+        return self.commission + self.slippage
+
+    def sell(self, day) -> float:
+        duty = self.stamp_duty
+        if self.stamp_duty_cut and pd.Timestamp(day) >= pd.Timestamp(self.stamp_duty_cut):
+            duty = self.stamp_duty_after
+        return self.commission + self.slippage + duty
+
+
+COSTS = {"cn": Costs(),
+         "us": Costs(commission=0.0, slippage=0.0005, stamp_duty=0.0, stamp_duty_cut=None,
+                     stamp_duty_after=0.0)}
+
+
+def price_limit(ticker: str, day) -> float | None:
+    """Daily price limit for an A-share (None = no limit, e.g. US / HK)."""
+    if not ticker.endswith((".SH", ".SZ", ".BJ")):
+        return None
+    code = ticker[:6]
+    if ticker.endswith(".BJ"):
+        return 0.30
+    if code.startswith("688"):
+        return 0.20                                   # STAR market, since its start in 2019
+    if code.startswith(("300", "301")) and pd.Timestamp(day) >= pd.Timestamp("2020-08-24"):
+        return 0.20                                   # ChiNext reform
+    return 0.10
+
+
+def tradable_masks(prices: pd.DataFrame) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """(can_buy, can_sell, returns) as T x N arrays. A day with no price is a suspension.
+    A close within 0.3% of the limit is treated as locked at the limit (no fills on that side)."""
+    ret = prices.pct_change(fill_method=None).to_numpy(dtype=float)
+    has = prices.notna().to_numpy()
+    up = np.zeros_like(has)
+    down = np.zeros_like(has)
+    days = prices.index
+    for j, tk in enumerate(prices.columns):
+        lim_old, lim_new = price_limit(tk, days[0]), price_limit(tk, days[-1])
+        if lim_old is None:
+            continue
+        lim = np.array([price_limit(tk, d) for d in days]) if lim_old != lim_new else lim_old
+        r = ret[:, j]
+        up[:, j] = r >= lim - 0.003
+        down[:, j] = r <= -(lim - 0.003)
+    up &= ~np.isnan(ret)
+    down &= ~np.isnan(ret)
+    return has & ~up, has & ~down, ret
+
+
+def make_trades(events: pd.DataFrame, prices: pd.DataFrame, long_sue: float, short_sue: float,
+                hold: int, entry_lag: int = 1, max_wait: int = 5, max_exit_wait: int = 20) -> pd.DataFrame:
+    """One row per trade: ticker, side (+1/-1), entry and exit positions in the price index."""
+    days = prices.index
+    col = {tk: j for j, tk in enumerate(prices.columns)}
+    can_buy, can_sell, _ = tradable_masks(prices)
+    rows = []
+    ev = events.dropna(subset=["sue", "day0"])
+    ev = ev[(ev["sue"] >= long_sue) | (ev["sue"] <= short_sue)]
+    for _, e in ev.iterrows():
+        j = col.get(e["ticker"])
+        if j is None:
+            continue
+        side = 1 if e["sue"] >= long_sue else -1
+        i0 = int(days.searchsorted(pd.Timestamp(e["day0"])))
+        open_ok = can_buy if side == 1 else can_sell          # opening a short = selling
+        close_ok = can_sell if side == 1 else can_buy
+        entry = None
+        for i in range(i0 + entry_lag, min(i0 + entry_lag + max_wait + 1, len(days))):
+            if open_ok[i, j]:
+                entry = i
+                break
+        if entry is None:
+            continue
+        exit_ = None
+        for i in range(entry + hold, min(entry + hold + max_exit_wait + 1, len(days))):
+            if close_ok[i, j]:
+                exit_ = i
+                break
+        if exit_ is None:
+            if entry + hold < len(days):
+                continue                                       # stuck for weeks: leave it out
+            exit_ = len(days) - 1                              # still open today: mark to market
+        rows.append({"ticker": e["ticker"], "side": side, "sue": e["sue"], "day0": e["day0"],
+                     "entry": entry, "exit": exit_, "entry_date": days[entry].date().isoformat(),
+                     "exit_date": days[exit_].date().isoformat(), "open": entry + hold >= len(days)})
+    return pd.DataFrame(rows)
+
+
+def run(events: pd.DataFrame, prices: pd.DataFrame, market: str = "cn", long_sue: float = 2.0,
+        short_sue: float = -2.0, hold: int = 60, costs: Costs | None = None, slots: int = 20,
+        entry_lag: int = 1) -> dict:
+    """Daily returns of the long book, short book, long-short and the benchmark, plus trades."""
+    from stockproof.research import BENCHMARKS
+    costs = costs or COSTS.get(market, Costs())
+    stocks = prices.drop(columns=[c for c in BENCHMARKS if c in prices.columns])
+    days = stocks.index
+    _, _, ret = tradable_masks(stocks)
+    ret0 = np.nan_to_num(ret)
+    bench = pd.DataFrame(ret, index=days).mean(axis=1, skipna=True).fillna(0.0)
+    trades = make_trades(events, stocks, long_sue, short_sue, hold, entry_lag=entry_lag)
+    T = len(days)
+    out = {"days": days, "trades": trades, "bench": bench}
+    for side, name in ((1, "long"), (-1, "short")):
+        s = np.zeros(T)
+        n = np.zeros(T)
+        net = []
+        if len(trades):
+            col = {tk: j for j, tk in enumerate(stocks.columns)}
+            for _, t in trades[trades["side"] == side].iterrows():
+                j, a, b = col[t["ticker"]], int(t["entry"]), int(t["exit"])
+                if b <= a:
+                    continue
+                r = ret0[a + 1:b + 1, j].copy()
+                r[0] -= costs.buy(days[a]) if side == 1 else costs.sell(days[a])
+                if not t["open"]:
+                    r[-1] -= costs.sell(days[b]) if side == 1 else costs.buy(days[b])
+                s[a + 1:b + 1] += r
+                n[a + 1:b + 1] += 1
+                gross = float(np.prod(1 + ret0[a + 1:b + 1, j]) - 1)
+                bench_ret = float(np.prod(1 + bench.to_numpy()[a + 1:b + 1]) - 1)
+                cost = (costs.buy(days[a]) + costs.sell(days[b])) if not t["open"] else costs.buy(days[a])
+                net.append(side * (gross - bench_ret) - cost)
+        # Capital is split into `slots` equal parts; parts without a position hold the market
+        # (an index fund). With more positions than slots, all positions share the capital equally.
+        # Without this, a day with one open trade would put everything into one stock.
+        k = np.maximum(n, slots)
+        b = bench.to_numpy()
+        book = pd.Series(np.where(n > 0, (s + (k - n) * b) / k, b), index=days)
+        out[name] = book
+        out[name + "_n"] = pd.Series(n, index=days)
+        out[name + "_trade_excess"] = net
+    # a short position earns the negative of the stock: long-short = long book minus short book
+    out["long_excess"] = out["long"] - bench
+    out["long_short"] = out["long"] - out["short"]          # the market parts cancel out
+    out["slots"] = slots
+    return out
+
+
+def _drawdown(r: pd.Series) -> float:
+    curve = (1 + r).cumprod()
+    return float((curve / curve.cummax() - 1).min()) if len(curve) else float("nan")
+
+
+def stats(r: pd.Series, active: pd.Series | None = None) -> dict:
+    """Annualized figures over the days the strategy was invested (or all days)."""
+    x = r[active > 0] if active is not None else r
+    if len(x) < 20:
+        return {"days": len(x)}
+    ann = (1 + x).prod() ** (252 / len(x)) - 1
+    vol = x.std(ddof=1) * math.sqrt(252)
+    t = x.mean() / (x.std(ddof=1) / math.sqrt(len(x))) if x.std(ddof=1) > 0 else float("nan")
+    return {"days": len(x), "ann_return": float(ann), "ann_vol": float(vol),
+            "sharpe": float(x.mean() / x.std(ddof=1) * math.sqrt(252)) if x.std(ddof=1) > 0 else float("nan"),
+            "t": float(t), "max_dd": _drawdown(x)}
+
+
+def by_year(r: pd.Series, active: pd.Series | None = None) -> pd.DataFrame:
+    x = r if active is None else r.where(active > 0, 0.0)
+    g = (1 + x).groupby(x.index.year).prod() - 1
+    return g.rename("return").to_frame()
+
+
+def summarize(bt: dict) -> dict:
+    """Numbers for the report."""
+    tr = bt["trades"]
+    out = {"n_trades": len(tr), "n_long": int((tr["side"] == 1).sum()) if len(tr) else 0,
+           "n_short": int((tr["side"] == -1).sum()) if len(tr) else 0}
+    if not len(tr):
+        return out
+    out["start"], out["end"] = tr["entry_date"].min(), tr["exit_date"].max()
+    live = pd.Series(0, index=bt["long_n"].index)
+    first = bt["long_n"].to_numpy().nonzero()[0]
+    if len(first):
+        live.iloc[first[0]:] = 1                              # from the first trade on
+    out["long_excess"] = stats(bt["long_excess"], live)
+    out["long"] = stats(bt["long"], live)
+    out["bench"] = stats(bt["bench"], live)
+    out["long_short"] = stats(bt["long_short"], live)
+    out["avg_positions"] = float(bt["long_n"][live > 0].mean())
+    out["slots"] = bt.get("slots")
+    for side in ("long", "short"):
+        net = pd.Series(bt[side + "_trade_excess"], dtype=float)
+        if len(net):
+            out[side + "_trade"] = {"n": len(net), "mean": float(net.mean()), "win": float((net > 0).mean()),
+                                    "t": float(net.mean() / (net.std(ddof=1) / math.sqrt(len(net))))
+                                    if len(net) > 1 and net.std(ddof=1) > 0 else float("nan")}
+    yrs = pd.concat([by_year(bt["long_excess"], live).rename(columns={"return": "long_excess"}),
+                     by_year(bt["long_short"], live).rename(columns={"return": "long_short"})], axis=1)
+    yrs = yrs[yrs.index >= bt["long_n"].index[first[0]].year] if len(first) else yrs
+    out["years"] = yrs
+    curve = pd.DataFrame({"long_excess": (1 + bt["long_excess"]).cumprod(),
+                          "long_short": (1 + bt["long_short"]).cumprod()})
+    first = bt["long_n"].to_numpy().nonzero()[0]
+    out["curve"] = curve.iloc[first[0]:] if len(first) else curve
+    return out
+
+
+def sweep(events: pd.DataFrame, prices: pd.DataFrame, market: str,
+          thresholds=(0.5, 1.0, 2.0), holds=(20, 60)) -> pd.DataFrame:
+    """Robustness: the same backtest with other SUE cut-offs and holding periods."""
+    rows = []
+    for th in thresholds:
+        for h in holds:
+            s = summarize(run(events, prices, market, th, -th, h))
+            le, lt = s.get("long_excess", {}), s.get("long_trade", {})
+            rows.append({"sue": th, "hold": h, "trades": s.get("n_long", 0),
+                         "ann_excess": le.get("ann_return"), "t": le.get("t"),
+                         "per_trade": lt.get("mean"), "win": lt.get("win"),
+                         "ls_ann": s.get("long_short", {}).get("ann_return")})
+    return pd.DataFrame(rows)
+
+
+def to_json(s: dict, params: dict) -> dict:
+    """A JSON-safe copy of summarize() for saving next to the research results."""
+    out = {k: v for k, v in s.items() if k not in ("years", "curve")}
+    out["params"] = params
+    if "years" in s:
+        y = s["years"]
+        out["years"] = [{"year": int(i), **{c: (None if pd.isna(v) else float(v)) for c, v in r.items()}}
+                        for i, r in y.iterrows()]
+    if "curve" in s:
+        c = s["curve"].groupby(pd.Grouper(freq="W")).tail(1)        # last real day of each week
+        out["curve"] = {"dates": [d.date().isoformat() for d in c.index],
+                        "long_excess": [round(float(v), 5) for v in c["long_excess"]],
+                        "long_short": [round(float(v), 5) for v in c["long_short"]]}
+    return out
+
+
+def full(events: pd.DataFrame, prices: pd.DataFrame, market: str, long_sue: float = 2.0,
+         hold: int = 60) -> dict:
+    """Main backtest + robustness sweep, ready for the report (JSON-safe)."""
+    s = summarize(run(events, prices, market, long_sue, -long_sue, hold))
+    free = Costs(commission=0.0, slippage=0.0, stamp_duty=0.0, stamp_duty_cut=None, stamp_duty_after=0.0)
+    g = summarize(run(events, prices, market, long_sue, -long_sue, hold, costs=free))
+    s["long_excess_gross"] = g.get("long_excess", {})
+    s["long_short_gross"] = g.get("long_short", {})
+    out = to_json(s, {"long_sue": long_sue, "short_sue": -long_sue, "hold": hold, "market": market,
+                      "costs": COSTS.get(market, Costs()).__dict__})
+    sw = sweep(events, prices, market)
+    out["sweep"] = [{k: (None if (isinstance(v, float) and math.isnan(v)) else v) for k, v in r.items()}
+                    for r in sw.to_dict("records")]
+    return out