stratiq-backtest 0.3.0__py3-none-any.whl

stratiq_backtest/__init__.py

@@ -0,0 +1,35 @@
+"""stratiq_backtest — a tiny, honest backtesting engine.
+
+Long-only signal backtests with full trade logs and a buy-and-hold
+comparison. No hidden assumptions: the methodology is documented in
+the README and every number the engine prints can be traced to a trade.
+"""
+
+from .backtest import BarData, BacktestResult, Strategy, Trade, run
+from .data import fetch_stooq, fetch_yahoo, load_csv, load_json
+from .indicators import atr_series, ema_series, rsi_series, sma
+from .stats import max_drawdown, summarize
+from .strategy import CrossoverStrategy
+from .synthetic import synthetic_bars
+
+__all__ = [
+    "BarData",
+    "BacktestResult",
+    "CrossoverStrategy",
+    "Strategy",
+    "Trade",
+    "atr_series",
+    "ema_series",
+    "fetch_stooq",
+    "fetch_yahoo",
+    "load_csv",
+    "load_json",
+    "max_drawdown",
+    "rsi_series",
+    "run",
+    "sma",
+    "summarize",
+    "synthetic_bars",
+]
+
+__version__ = "0.3.0"

stratiq_backtest/backtest.py

@@ -0,0 +1,130 @@
+"""Core backtest loop.
+
+Methodology (documented so every number is auditable):
+- Long-only, fully invested-or-cash. No leverage, no shorting.
+- Trades execute AT the close of the bar that generates the signal:
+  the strategy sees bar i's close, the trade prints at bar i's close.
+- NO look-ahead: a position entered on bar i does NOT earn bar i's
+  return (that move already happened before the trade printed). It
+  starts earning on bar i+1. A position exited on bar i DOES earn
+  bar i's return (it was exposed during the bar, sold at its close).
+  NOTE: v0.1.0 credited the signal bar's own return to the new
+  position — that was a look-ahead error, fixed in v0.2.0.
+- No commissions, no slippage, no taxes are modeled. Real trading
+  will do worse than these numbers by roughly those costs.
+- Use dividend/split-adjusted closes or your returns will be wrong.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BarData:
+    dates: list  # ISO date strings, one per bar
+    closes: list  # floats, preferably dividend/split-adjusted
+
+    def __len__(self):
+        if len(self.dates) != len(self.closes):
+            raise ValueError("dates and closes must be the same length")
+        return len(self.dates)
+
+
+@dataclass
+class Trade:
+    entry_date: str
+    entry: float
+    exit_date: str
+    exit: float
+    return_pct: float
+    open_at_end: bool = False
+
+
+@dataclass
+class BacktestResult:
+    trades: list = field(default_factory=list)
+    equity: list = field(default_factory=list)  # starts at 1.0, one entry per bar + 1
+    in_market_bars: int = 0
+    warmup: int = 0
+
+
+class Strategy:
+    """Decide the position after seeing bar i's close.
+
+    on_bar(i, data, position) -> new position (0 = cash, 1 = long).
+    The returned position takes effect after bar i's close (see the
+    no-look-ahead rule above). Strategies may keep state between bars;
+    reset() is called before each run.
+    """
+
+    def reset(self):
+        pass
+
+    def on_bar(self, i: int, data: BarData, position: int) -> int:
+        raise NotImplementedError
+
+
+def run(data: BarData, strategy: Strategy, warmup: int) -> BacktestResult:
+    """Run a backtest. Signals are evaluated from bar `warmup` onward."""
+    n = len(data)
+    if warmup < 1 or warmup >= n:
+        raise ValueError("warmup must be >= 1 and < len(data)")
+    strategy.reset()
+    closes, dates = data.closes, data.dates
+    position = 0
+    entry_px = entry_date = None
+    trades: list[Trade] = []
+    equity = [1.0]
+    in_market = 0
+
+    for i in range(n):
+        # 1) The position held DURING bar i earns bar i's return.
+        if position == 1:
+            in_market += 1
+            equity.append(equity[-1] * (closes[i] / closes[i - 1] if i > 0 else 1.0))
+        else:
+            equity.append(equity[-1])
+        # 2) Then the strategy reacts to bar i's close. A change takes
+        # effect after the close: an entry printed at closes[i] starts
+        # earning on bar i+1 (no look-ahead); an exit printed at
+        # closes[i] keeps the return already earned during bar i.
+        if i >= warmup:
+            want = strategy.on_bar(i, data, position)
+            if want not in (0, 1):
+                raise ValueError("strategy must return 0 (cash) or 1 (long)")
+            if want != position:
+                if want == 1:
+                    position = 1
+                    entry_px = closes[i]
+                    entry_date = dates[i]
+                else:
+                    ret = closes[i] / entry_px - 1
+                    trades.append(
+                        Trade(
+                            entry_date=entry_date,
+                            entry=round(entry_px, 2),
+                            exit_date=dates[i],
+                            exit=round(closes[i], 2),
+                            return_pct=round(ret * 100, 2),
+                        )
+                    )
+                    position = 0
+                    entry_px = entry_date = None
+
+    # Close any open position at the final close so equity is comparable.
+    if position == 1:
+        ret = closes[-1] / entry_px - 1
+        trades.append(
+            Trade(
+                entry_date=entry_date,
+                entry=round(entry_px, 2),
+                exit_date=dates[-1],
+                exit=round(closes[-1], 2),
+                return_pct=round(ret * 100, 2),
+                open_at_end=True,
+            )
+        )
+
+    return BacktestResult(
+        trades=trades, equity=equity, in_market_bars=in_market, warmup=warmup
+    )

stratiq_backtest/data.py

@@ -0,0 +1,111 @@
+"""Data loading. Prefer dividend/split-adjusted closes — unadjusted
+data makes every backtest a lie about the past (dividends vanish)."""
+import csv
+import datetime
+import json
+import urllib.request
+
+from .backtest import BarData
+
+
+def load_json(path) -> BarData:
+    """Load {"dates": [...], "closes": [...]} or the compact
+    {"ts": [unix timestamps], "adj": [adjusted closes]} format."""
+    with open(path) as f:
+        d = json.load(f)
+    if "ts" in d and "adj" in d:
+        dates = [
+            datetime.datetime.fromtimestamp(t, datetime.UTC).date().isoformat()
+            for t in d["ts"]
+        ]
+        closes = [float(x) for x in d["adj"]]
+    elif "dates" in d and "closes" in d:
+        dates = list(d["dates"])
+        closes = [float(x) for x in d["closes"]]
+    else:
+        raise ValueError("JSON must have {dates, closes} or {ts, adj}")
+    return BarData(dates=dates, closes=closes)
+
+
+def load_csv(path, date_col="date", close_col="close") -> BarData:
+    """Load a CSV with a date column and a close column."""
+    dates, closes = [], []
+    with open(path, newline="") as f:
+        for row in csv.DictReader(f):
+            if not row.get(date_col) or not row.get(close_col):
+                continue
+            try:
+                px = float(row[close_col])
+            except ValueError:
+                continue  # e.g. Stooq "N/D" rows
+            dates.append(row[date_col][:10])
+            closes.append(px)
+    if not dates:
+        raise ValueError(f"no usable rows in {path}")
+    return BarData(dates=dates, closes=closes)
+
+
+def fetch_yahoo(symbol: str, start: str = "2019-01-01", end: str | None = None) -> BarData:
+    """Free daily bars from Yahoo Finance's chart API (no API key), using
+    the ADJUSTED close series — dividend- and split-adjusted, the only
+    honest basis for a long-window backtest. Unofficial endpoint: it can
+    rate-limit or change without notice, so callers must fail loudly."""
+    if end is None:
+        end = datetime.date.today().isoformat()
+    p1 = int(datetime.datetime.fromisoformat(start).replace(tzinfo=datetime.UTC).timestamp())
+    p2 = int(datetime.datetime.fromisoformat(end).replace(tzinfo=datetime.UTC).timestamp()) + 86400
+    url = (
+        "https://query1.finance.yahoo.com/v8/finance/chart/"
+        f"{symbol.upper()}?period1={p1}&period2={p2}&interval=1d&events=div,split"
+    )
+    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0 stratiq-backtest/0.3"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        payload = json.loads(r.read().decode("utf-8"))
+    result = (payload.get("chart") or {}).get("result") or []
+    if not result:
+        raise ValueError(f"no data returned for {symbol}")
+    result = result[0]
+    stamps = result.get("timestamp") or []
+    adj = ((result.get("indicators") or {}).get("adjclose") or [{}])[0].get("adjclose")
+    if adj is None:  # fall back to raw closes rather than nothing
+        adj = ((result.get("indicators") or {}).get("quote") or [{}])[0].get("close")
+    if not stamps or not adj:
+        raise ValueError(f"no price series returned for {symbol}")
+    dates, closes = [], []
+    for t, px in zip(stamps, adj):
+        if px is None:
+            continue
+        dates.append(datetime.datetime.fromtimestamp(t, datetime.UTC).date().isoformat())
+        closes.append(float(px))
+    if not dates:
+        raise ValueError(f"no usable bars returned for {symbol}")
+    return BarData(dates=dates, closes=closes)
+
+
+def fetch_stooq(symbol: str, start: str = "2019-01-01", end: str | None = None) -> BarData:
+    """Free daily bars from Stooq (no API key). NOTE: Stooq's free CSV is
+    split-adjusted but NOT dividend-adjusted — fine for experimenting,
+    not for publishing numbers. NOTE 2: as of 2026-11 Stooq serves a
+    JavaScript browser-verification challenge to plain HTTP clients, so
+    this fetch currently fails against the live site; fetch_yahoo is the
+    working free path."""
+    if end is None:
+        end = datetime.date.today().isoformat()
+    url = (
+        "https://stooq.com/q/d/l/?s="
+        f"{symbol.lower()}.us&d1={start.replace('-', '')}"
+        f"&d2={end.replace('-', '')}&i=d"
+    )
+    req = urllib.request.Request(url, headers={"User-Agent": "stratiq-backtest/0.1"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        text = r.read().decode("utf-8")
+    dates, closes = [], []
+    for line in text.strip().splitlines()[1:]:  # skip header
+        parts = line.split(",")
+        if len(parts) < 5 or parts[4] in ("", "N/D"):
+            continue
+        dates.append(parts[0])
+        closes.append(float(parts[4]))
+    if not dates:
+        raise ValueError(f"no data returned for {symbol}")
+    return BarData(dates=dates, closes=closes)

stratiq_backtest/indicators.py

@@ -0,0 +1,82 @@
+"""Classic technical indicators. All functions use only data available
+at or before the bar they are evaluated on — no lookahead."""
+
+
+def sma(values, n, i):
+    """Simple moving average of the n values ending at index i (inclusive)."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    if i - n + 1 < 0:
+        raise ValueError(f"not enough data: need {n} values ending at {i}")
+    return sum(values[i - n + 1 : i + 1]) / n
+
+
+def ema_series(values, n):
+    """Exponential moving average over the whole series (seeded with SMA)."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    k = 2 / (n + 1)
+    out = []
+    ema = None
+    for i, v in enumerate(values):
+        if i < n - 1:
+            out.append(None)
+        elif i == n - 1:
+            ema = sum(values[:n]) / n
+            out.append(ema)
+        else:
+            ema = v * k + ema * (1 - k)
+            out.append(ema)
+    return out
+
+
+def rsi_series(values, n=14):
+    """Relative Strength Index (Wilder's smoothing). None for the first n bars."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    out = [None] * len(values)
+    if len(values) <= n:
+        return out
+    gains, losses = [], []
+    for i in range(1, n + 1):
+        chg = values[i] - values[i - 1]
+        gains.append(max(chg, 0))
+        losses.append(max(-chg, 0))
+    avg_gain = sum(gains) / n
+    avg_loss = sum(losses) / n
+    for i in range(n, len(values)):
+        if i > n:
+            chg = values[i] - values[i - 1]
+            avg_gain = (avg_gain * (n - 1) + max(chg, 0)) / n
+            avg_loss = (avg_loss * (n - 1) + max(-chg, 0)) / n
+        if avg_loss == 0:
+            out[i] = 100.0
+        else:
+            rs = avg_gain / avg_loss
+            out[i] = 100 - 100 / (1 + rs)
+    return out
+
+
+def atr_series(highs, lows, closes, n=14):
+    """Average True Range (Wilder's smoothing). None for the first n bars."""
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    if not (len(highs) == len(lows) == len(closes)):
+        raise ValueError("highs, lows, closes must be the same length")
+    out = [None] * len(closes)
+    if len(closes) <= n:
+        return out
+    trs = []
+    for i in range(1, len(closes)):
+        tr = max(
+            highs[i] - lows[i],
+            abs(highs[i] - closes[i - 1]),
+            abs(lows[i] - closes[i - 1]),
+        )
+        trs.append(tr)
+    atr = sum(trs[:n]) / n
+    out[n] = atr
+    for i in range(n + 1, len(closes)):
+        atr = (atr * (n - 1) + trs[i - 1]) / n
+        out[i] = atr
+    return out

stratiq_backtest/mcp_server.py

@@ -0,0 +1,205 @@
+"""StratIQ backtest engine as an MCP (Model Context Protocol) server.
+
+Stdio transport, newline-delimited JSON-RPC 2.0, standard library only —
+the same zero-dependency discipline as the rest of the package. Any MCP
+client (Claude, Claude Code, Cursor, and other AI assistants) can then
+run an honest backtest *inside the assistant session*: every result is
+shown next to buy-and-hold, with the full trade log and the data caveats
+printed in the result itself. A backtest that hides its benchmark or its
+data limits is a sales pitch, not a receipt.
+
+Tools:
+  backtest_crossover  — moving-average crossover on a real ticker
+                        (daily adjusted bars via Yahoo Finance; see the
+                        honesty footer the tool returns with every result).
+  stratiq_track_record — StratIQ's live published track record, fetched
+                        from stratiqai.app at call time; fails closed to
+                        a bare link when the fetch does not succeed, so
+                        the server never quotes a stale record.
+
+Run:  python -m stratiq_backtest.mcp_server
+"""
+import json
+import sys
+import urllib.request
+
+from .backtest import run
+from .data import fetch_yahoo
+from .stats import summarize
+from .strategy import CrossoverStrategy
+
+SERVER_NAME = "stratiq-backtest"
+SERVER_VERSION = "0.3.0"
+# The MCP protocol revision this server speaks. Clients that offer a
+# different revision still get a working session: we answer with ours.
+PROTOCOL_VERSION = "2024-11-05"
+
+TRACK_RECORD_URL = "https://stratiqai.app/track-record"
+TRACK_RECORD_API = "https://stratiqai.app/api/track-record"
+TEST_MY_RULE_URL = "https://stratiqai.app/test-my-rule?src=mcp"
+
+DATA_HONESTY = (
+    "Data: daily ADJUSTED closes from Yahoo Finance's free chart API "
+    "(dividend- and split-adjusted; unofficial endpoint, may rate-limit). "
+    "No commissions, slippage, or taxes are modeled — real trading does "
+    "worse by roughly those costs. Past performance does not predict "
+    "future returns; this is a historical test, not financial advice."
+)
+
+ATTRIBUTION = (
+    "Engine: stratiq-backtest by StratIQ (https://stratiqai.app). "
+    f"Test your own rule free: {TEST_MY_RULE_URL} · "
+    f"StratIQ's live, graded track record: {TRACK_RECORD_URL}"
+)
+
+
+def tool_backtest_crossover(args: dict) -> dict:
+    ticker = str(args.get("ticker", "")).strip().upper()
+    if not ticker or not ticker.replace(".", "").replace("-", "").isalnum():
+        raise ValueError("ticker must be a plain symbol like AAPL or SPY")
+    fast = int(args.get("fast", 50))
+    slow = int(args.get("slow", 200))
+    start = str(args.get("start", "2019-01-01"))
+    strat = CrossoverStrategy(fast=fast, slow=slow)  # validates fast < slow
+    data = fetch_yahoo(ticker, start=start)
+    if len(data.closes) <= strat.warmup + 2:
+        raise ValueError(
+            f"not enough daily bars for {ticker} since {start} "
+            f"to run a {fast}/{slow} crossover"
+        )
+    result = run(data, strat, warmup=strat.warmup)
+    summary = summarize(data, result)
+    return {
+        "ticker": ticker,
+        "rule": f"{fast}/{slow} moving-average crossover (long when fast > slow, else cash)",
+        **summary,
+        "honesty": DATA_HONESTY,
+        "attribution": ATTRIBUTION,
+    }
+
+
+def tool_track_record(_args: dict) -> dict:
+    """Live record or a bare link — never a remembered number."""
+    try:
+        req = urllib.request.Request(
+            TRACK_RECORD_API, headers={"User-Agent": f"{SERVER_NAME}/{SERVER_VERSION}"}
+        )
+        with urllib.request.urlopen(req, timeout=15) as r:
+            payload = json.loads(r.read().decode("utf-8"))
+        return {
+            "source": TRACK_RECORD_API,
+            "track_record": payload,
+            "page": TRACK_RECORD_URL,
+            "attribution": ATTRIBUTION,
+        }
+    except Exception:
+        return {
+            "source": "unavailable — failing closed to the live page",
+            "page": TRACK_RECORD_URL,
+            "note": (
+                "The live track-record feed could not be fetched, so no "
+                "record numbers are quoted here. Read the current record "
+                f"on the page itself: {TRACK_RECORD_URL}"
+            ),
+            "attribution": ATTRIBUTION,
+        }
+
+
+TOOLS = {
+    "backtest_crossover": {
+        "fn": tool_backtest_crossover,
+        "description": (
+            "Backtest a moving-average crossover rule on a real ticker and "
+            "get the honest receipt: strategy return vs buy-and-hold over "
+            "the same window, CAGR, max drawdown, win rate, and the full "
+            "trade log. Long-only; long when the fast average is above the "
+            "slow one, in cash otherwise."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "ticker": {"type": "string", "description": "US ticker symbol, e.g. AAPL, SPY, QQQ"},
+                "fast": {"type": "integer", "default": 50, "description": "Fast moving-average length in days"},
+                "slow": {"type": "integer", "default": 200, "description": "Slow moving-average length in days"},
+                "start": {"type": "string", "default": "2019-01-01", "description": "First date to load, YYYY-MM-DD"},
+            },
+            "required": ["ticker"],
+        },
+    },
+    "stratiq_track_record": {
+        "fn": tool_track_record,
+        "description": (
+            "Fetch StratIQ's live published track record (daily stock "
+            "picks, graded at the Friday close of their publication week, "
+            "wins and losses) from stratiqai.app at call time."
+        ),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+}
+
+
+def handle(msg: dict) -> dict | None:
+    """One JSON-RPC message in, one response out (None for notifications)."""
+    method = msg.get("method", "")
+    mid = msg.get("id")
+    if method == "initialize":
+        return _ok(mid, {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": SERVER_NAME, "version": SERVER_VERSION},
+        })
+    if method.startswith("notifications/"):
+        return None
+    if method == "ping":
+        return _ok(mid, {})
+    if method == "tools/list":
+        return _ok(mid, {"tools": [
+            {"name": name, "description": t["description"], "inputSchema": t["inputSchema"]}
+            for name, t in TOOLS.items()
+        ]})
+    if method == "tools/call":
+        params = msg.get("params") or {}
+        name = params.get("name", "")
+        tool = TOOLS.get(name)
+        if tool is None:
+            return _err(mid, -32602, f"unknown tool: {name}")
+        try:
+            result = tool["fn"](params.get("arguments") or {})
+            return _ok(mid, {"content": [
+                {"type": "text", "text": json.dumps(result, indent=2)}
+            ]})
+        except Exception as e:  # tool errors are results, not protocol errors
+            return _ok(mid, {
+                "content": [{"type": "text", "text": f"Error: {e}"}],
+                "isError": True,
+            })
+    return _err(mid, -32601, f"method not found: {method}")
+
+
+def _ok(mid, result):
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def _err(mid, code, message):
+    return {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": message}}
+
+
+def main(instream=None, outstream=None):
+    instream = instream or sys.stdin
+    outstream = outstream or sys.stdout
+    for line in instream:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue  # a garbled line must never kill the session
+        resp = handle(msg)
+        if resp is not None:
+            outstream.write(json.dumps(resp) + "\n")
+            outstream.flush()
+
+
+if __name__ == "__main__":
+    main()

stratiq_backtest/stats.py

@@ -0,0 +1,65 @@
+"""Performance statistics, always shown next to buy-and-hold.
+
+A strategy that beats nothing is a hobby. Every summary includes the
+do-nothing alternative over the same period so the numbers mean something.
+"""
+from dataclasses import asdict
+
+TRADING_DAYS = 252
+
+
+def max_drawdown(equity) -> float:
+    """Largest peak-to-trough decline, as a fraction (negative or zero)."""
+    peak = equity[0]
+    mdd = 0.0
+    for v in equity:
+        peak = max(peak, v)
+        mdd = min(mdd, v / peak - 1)
+    return mdd
+
+
+def summarize(data, result) -> dict:
+    """Full honest summary: strategy stats + buy-and-hold over the same window."""
+    n = len(data)
+    warmup = result.warmup
+    closes = data.closes
+    # Bars [warmup, n-1] are the strategy's active window.
+    span_bars = n - warmup
+    if span_bars < 2:
+        raise ValueError("not enough bars after warmup")
+
+    strat_ret = result.equity[-1] - 1
+    years = span_bars / TRADING_DAYS
+    cagr = result.equity[-1] ** (1 / years) - 1
+
+    bh_ret = closes[-1] / closes[warmup] - 1
+    bh_cagr = (1 + bh_ret) ** (1 / years) - 1
+    bh_eq = [c / closes[warmup] for c in closes[warmup:]]
+
+    trades = result.trades
+    wins = [t for t in trades if t.return_pct > 0]
+    losses = [t for t in trades if t.return_pct <= 0]
+
+    def trade_dict(t):
+        return asdict(t) if t is not None else None
+
+    return {
+        "data_range": [data.dates[0], data.dates[-1]],
+        "strategy_period": [data.dates[warmup], data.dates[-1]],
+        "n_trades": len(trades),
+        "win_rate_pct": round(100 * len(wins) / len(trades), 1) if trades else 0.0,
+        "avg_win_pct": round(sum(t.return_pct for t in wins) / len(wins), 2) if wins else 0.0,
+        "avg_loss_pct": round(sum(t.return_pct for t in losses) / len(losses), 2)
+        if losses
+        else 0.0,
+        "strategy_total_return_pct": round(strat_ret * 100, 1),
+        "strategy_cagr_pct": round(cagr * 100, 1),
+        "strategy_max_dd_pct": round(max_drawdown(result.equity) * 100, 1),
+        "buyhold_total_return_pct": round(bh_ret * 100, 1),
+        "buyhold_cagr_pct": round(bh_cagr * 100, 1),
+        "buyhold_max_dd_pct": round(max_drawdown(bh_eq) * 100, 1),
+        "time_in_market_pct": round(100 * result.in_market_bars / span_bars, 1),
+        "best_trade": trade_dict(max(trades, key=lambda t: t.return_pct)) if trades else None,
+        "worst_trade": trade_dict(min(trades, key=lambda t: t.return_pct)) if trades else None,
+        "trades": [asdict(t) for t in trades],
+    }

stratiq_backtest/strategy.py

@@ -0,0 +1,37 @@
+"""Ready-made strategies. Subclass Strategy (see backtest.py) for your own."""
+from .backtest import BarData, Strategy
+from .indicators import sma
+
+
+class CrossoverStrategy(Strategy):
+    """Go long when the fast SMA crosses above the slow SMA; exit (to cash)
+    when it crosses back below. Hysteretic: no signal, no change.
+
+    Pass warmup=strategy.warmup to run(). warmup = slow - 1, the first bar
+    on which both averages are defined.
+    """
+
+    def __init__(self, fast: int = 50, slow: int = 200):
+        if not 1 < fast < slow:
+            raise ValueError("need 1 < fast < slow")
+        self.fast = fast
+        self.slow = slow
+
+    @property
+    def warmup(self) -> int:
+        return self.slow - 1
+
+    def on_bar(self, i: int, data: BarData, position: int) -> int:
+        # No signal until both the current AND previous averages are
+        # defined — comparing against a half-formed average would be
+        # peeking at a signal that doesn't exist yet.
+        if i - 1 < self.slow - 1:
+            return position
+        c = data.closes
+        f, s = sma(c, self.fast, i), sma(c, self.slow, i)
+        fp, sp = sma(c, self.fast, i - 1), sma(c, self.slow, i - 1)
+        if position == 0 and fp <= sp and f > s:
+            return 1
+        if position == 1 and fp >= sp and f < s:
+            return 0
+        return position

stratiq_backtest/synthetic.py

@@ -0,0 +1,47 @@
+"""Deterministic SYNTHETIC price series for examples and tests.
+
+These are NOT real market data: a seeded geometric Brownian motion
+with a mild upward drift. They exist so the bundled example is
+reproducible forever without redistributing anyone's price data.
+
+Never publish performance numbers computed on this data as if they
+were real. For real data, use fetch_stooq() (split-adjusted only —
+fine for experimenting, not for publishing) or load your own
+dividend/split-adjusted closes.
+"""
+import datetime
+import math
+import random
+
+from .backtest import BarData
+
+
+def synthetic_bars(
+    n: int = 1500,
+    seed: int = 42,
+    start: str = "2020-01-01",
+    start_px: float = 100.0,
+    drift: float = 0.0004,
+    vol: float = 0.012,
+) -> BarData:
+    """Generate n daily bars of synthetic closes from a seeded PRNG.
+
+    Same seed -> identical series, forever. Weekends are skipped so
+    the dates look like market data.
+    """
+    if n < 1:
+        raise ValueError("n must be >= 1")
+    rng = random.Random(seed)
+    closes = []
+    px = start_px
+    for _ in range(n):
+        px *= math.exp(drift - 0.5 * vol * vol + vol * rng.gauss(0, 1))
+        closes.append(round(px, 2))
+    d0 = datetime.date.fromisoformat(start)
+    dates = []
+    d = d0
+    while len(dates) < n:
+        if d.weekday() < 5:  # Mon-Fri only
+            dates.append(d.isoformat())
+        d += datetime.timedelta(days=1)
+    return BarData(dates=dates, closes=closes)

stratiq_backtest-0.3.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: stratiq-backtest
+Version: 0.3.0
+Summary: A tiny, honest backtesting engine: long-only signal backtests with full trade logs and buy-and-hold comparison.
+Author: StratIQ
+License: MIT
+Project-URL: Homepage, https://stratiqai.app/track-record
+Project-URL: Repository, https://github.com/germygrimes/stratiq-backtest
+Keywords: backtest,trading,quant,systematic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stratiq-backtest
+
+A tiny, honest backtesting engine. Long-only signal backtests with full trade logs — and every result shown next to the do-nothing alternative, because a strategy that beats nothing is a hobby.
+
+This is the engine behind [StratIQ's public track record](https://stratiqai.app/track-record), where every backtest is published with wins and losses.
+
+## Install
+
+```bash
+pip install stratiq-backtest
+```
+
+Or from source: `pip install .` — zero dependencies, stdlib only.
+
+## Quickstart
+
+```python
+from stratiq_backtest import CrossoverStrategy, run, summarize, synthetic_bars
+
+data = synthetic_bars(n=1500, seed=42)   # reproducible demo data (NOT real market data)
+strat = CrossoverStrategy(fast=50, slow=200)   # golden cross
+result = run(data, strat, warmup=strat.warmup)
+stats = summarize(data, result)
+
+print(stats["strategy_total_return_pct"], "vs buy-and-hold",
+      stats["buyhold_total_return_pct"])
+for t in stats["trades"]:
+    print(t)
+```
+
+Run the bundled example (golden cross on synthetic data):
+
+```bash
+python3 examples/golden_cross_synthetic.py
+```
+
+## Execution semantics (read this before trusting a number)
+
+- **Trades print at the close of the bar that generates the signal.** The strategy sees bar *i*'s close; the trade executes at bar *i*'s close.
+- **No look-ahead, ever.** A position entered on bar *i* does **not** earn bar *i*'s return — that move already happened before the trade printed. It starts earning on bar *i+1*. A position exited on bar *i* **does** earn bar *i*'s return (it was exposed during the bar, sold at its close).
+- Long-only, fully invested-or-cash. No leverage, no shorting. No commissions, no slippage, no taxes — real trading will do worse by roughly those costs.
+- Use dividend/split-adjusted closes or your returns will be wrong.
+
+> **Correction note (v0.2.0):** v0.1.0 credited each new position with the signal bar's own price move. That is look-ahead bias — the signal only exists after the bar closes — so v0.1.0 results were biased and unreliable, and must be re-run. (Note: "biased" does not always mean "overstated" — the old loop also dropped exit-bar returns, so on some datasets the corrected run comes out higher.) v0.2.0 fixes the execution timing and adds regression tests pinning the corrected behavior. If you published numbers computed with v0.1.0, re-run them.
+
+## Data
+
+The repo ships **no real market data**. `synthetic_bars()` generates a deterministic seeded random walk for examples and tests — reproducible forever, and clearly labeled synthetic. Never publish performance numbers computed on it as if they were real.
+
+For real data:
+- `fetch_yahoo(symbol)` — free daily bars from Yahoo Finance's chart API, adjusted close (dividend- and split-adjusted). Unofficial endpoint; fails loudly.
+- `fetch_stooq(symbol)` — free daily bars from Stooq, no API key. **Split-adjusted but NOT dividend-adjusted**: fine for experimenting, not for publishing numbers. (As of 2026-11 Stooq serves a JavaScript browser check to plain HTTP clients, so this path currently fails live; `fetch_yahoo` is the working one.)
+- `load_json()` / `load_csv()` — bring your own dividend/split-adjusted closes.
+
+## Use it inside your AI assistant (MCP)
+
+The engine ships an [MCP](https://modelcontextprotocol.io) server, so Claude, Claude Code, Cursor, and other MCP clients can backtest inside the conversation — every result arrives with buy-and-hold next to it, the full trade log, the data caveats, and a link to test your own rule.
+
+```bash
+python3 -m stratiq_backtest.mcp_server
+```
+
+MCP client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "stratiq-backtest": {
+      "command": "stratiq-backtest-mcp"
+    }
+  }
+}
+```
+
+Tools:
+
+- `backtest_crossover` — `{ticker, fast=50, slow=200, start="2019-01-01"}`. Real daily bars via Yahoo Finance's adjusted-close series (dividend- and split-adjusted — the result carries its data caveats in the result).
+- `stratiq_track_record` — StratIQ's live graded record, fetched from stratiqai.app at call time. If the feed is unreachable it returns the page link and **no numbers** — a stale record is worse than none.
+
+## Write your own strategy
+
+```python
+from stratiq_backtest import Strategy
+
+class MyStrategy(Strategy):
+    def on_bar(self, i, data, position):
+        # i: current bar index, data.closes / data.dates available.
+        # Return 1 to be long, 0 for cash. The new position takes
+        # effect AFTER bar i's close (see execution semantics above).
+        ...
+```
+
+Warm up indicators with `warmup=` so signals only fire on fully-formed values.
+
+## Tests
+
+```bash
+python3 -m pytest tests/
+```
+
+Happy paths, failure modes, edge cases — including regression tests that pin the no-look-ahead contract above.

stratiq_backtest-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+stratiq_backtest/__init__.py,sha256=jF5A1i10INeoP-WdTxTdio_CWp5ZYhOV2gL8-EvTXUo,924
+stratiq_backtest/backtest.py,sha256=s-bY4qmNWZxpXItJftppeqkMo-J9ZwG9i7sJxv6pWe0,4561
+stratiq_backtest/data.py,sha256=MRol5JYvco7bupmv79qQ2k8y92LXZVwfh9WEh0cb-ec,4769
+stratiq_backtest/indicators.py,sha256=IHQYqvdwGAypypMRTVXK1Q5MDzVxquLHGTFnZhbbbGI,2549
+stratiq_backtest/mcp_server.py,sha256=Hx5q6mi117u81ZcR-go13gmrkArRqq5Ie5ekR1N-uTs,7953
+stratiq_backtest/stats.py,sha256=ERp-r_5_BLltHc_i-cmgVhmyloeW6EzNW1vpFnes6Y4,2511
+stratiq_backtest/strategy.py,sha256=7pZdHwTw_s-HuSmCy7pX1XG1h4UDeaiXoj5apLPtfBw,1354
+stratiq_backtest/synthetic.py,sha256=Oba8IUxqo5Z05SIQKUV8GOwP_A-4SLZOINlFPH670rs,1455
+stratiq_backtest-0.3.0.dist-info/licenses/LICENSE,sha256=iOhQzkbQBFdABRWD9u4HbHzZPLvrFHVGWGJTWUxAN2o,1064
+stratiq_backtest-0.3.0.dist-info/METADATA,sha256=pSOG-8PfczmlhNHP-OTPE9gpd-bkHJIERr2L_Q7flcs,5263
+stratiq_backtest-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+stratiq_backtest-0.3.0.dist-info/entry_points.txt,sha256=zxSnfR894JkHCRhlDu9n_1obwJxc9uHB1YO0nTR5rEU,74
+stratiq_backtest-0.3.0.dist-info/top_level.txt,sha256=kO2C2Y71MigK02tac1Z980R8x0LBNexwFGlggRtPufI,17
+stratiq_backtest-0.3.0.dist-info/RECORD,,

stratiq_backtest-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stratiq_backtest-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stratiq-backtest-mcp = stratiq_backtest.mcp_server:main

stratiq_backtest-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StratIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stratiq_backtest-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stratiq_backtest