backtestchat 0.1.0__py3-none-any.whl

backtestchat/strategy/engine.py

@@ -0,0 +1,181 @@
+"""Pure backtest engine (no I/O).
+
+Annualization goes through broker.base.bars_per_year(interval); crypto only
+(24/7/365), so there is no asset-class branch.
+
+Long/flat position model: fully invested when the strategy signal
+is 1, fully in cash when 0. Signals are computed on a bar's close and the
+resulting position is held over the NEXT bar (next-bar fill) to avoid look-ahead
+bias. Costs/slippage are off by default (cost_bps=0) but wired so they can be
+turned on without changing callers.
+"""
+
+import math
+
+from backtestchat.broker.base import bars_per_year
+from backtestchat.strategy.registry import get_signal_fn, strategy_warmup
+
+DEFAULT_INTERVAL = "1d"
+DEFAULT_STARTING_EQUITY = 10_000.0
+
+
+def _pct_returns(closes):
+    returns = [0.0]
+
+    for index in range(1, len(closes)):
+        prev = closes[index - 1]
+        returns.append((closes[index] / prev - 1.0) if prev else 0.0)
+
+    return returns
+
+
+def _max_drawdown(equity):
+    peak = equity[0] if equity else 0.0
+    max_dd = 0.0
+
+    for value in equity:
+        if value > peak:
+            peak = value
+
+        if peak > 0:
+            dd = (value - peak) / peak
+
+            if dd < max_dd:
+                max_dd = dd
+
+    return max_dd * 100.0
+
+
+def run_backtest(bars, strategy_type, params, interval=DEFAULT_INTERVAL,
+                 starting_equity=DEFAULT_STARTING_EQUITY, cost_bps=0.0):
+    """Run a long/flat backtest over time-ordered OHLCV bars.
+
+    `bars` is a list of {ts, open, high, low, close, volume}. The strategy's
+    signal function (looked up by strategy_type) returns a 0/1 target position
+    per bar; positions are held next-bar to avoid look-ahead. Returns
+    {"equityCurve": [{ts, equity}], "trades": [{ts, side, price}], "metrics": {...}}.
+    Raises ValueError if there aren't enough bars for the strategy's warmup.
+    """
+    warmup = strategy_warmup(strategy_type, params)
+    if len(bars) <= warmup:
+        raise ValueError(
+            f"Not enough bars ({len(bars)}) for the {warmup}-bar warmup of this strategy."
+        )
+
+    signal_fn = get_signal_fn(strategy_type)
+    signals = signal_fn(bars, params)
+
+    return simulate(bars, signals, interval=interval,
+                    starting_equity=starting_equity, cost_bps=cost_bps)
+
+
+def simulate(bars, positions, interval=DEFAULT_INTERVAL,
+             starting_equity=DEFAULT_STARTING_EQUITY, cost_bps=0.0):
+    """Run a long/flat backtest from a precomputed 0/1 position series.
+
+    `positions[i]` is the target position computed from information available at
+    the CLOSE of bar i; it is held over bar i+1 (next-bar fill) to avoid
+    look-ahead. Returns
+    {"equityCurve": [{ts, equity}], "trades": [{ts, side, price}], "metrics": {...}}.
+    """
+    closes = [bar["close"] for bar in bars]
+    timestamps = [bar["ts"] for bar in bars]
+    bar_returns = _pct_returns(closes)
+    cost = cost_bps / 10_000.0
+
+    equity = starting_equity
+    equity_curve = [{"ts": timestamps[0], "equity": round(equity, 2)}]
+    trades = []
+    strategy_returns = []
+    invested_bars = 0
+    prev_position = 0
+
+    # Next-bar fill: position held over bar i is the position from bar i-1.
+    for index in range(1, len(closes)):
+        position = positions[index - 1] or 0
+
+        if position != prev_position:
+            side = "buy" if position == 1 else "sell"
+            trades.append({"ts": timestamps[index], "side": side, "price": round(closes[index], 4)})
+
+            # Apply a transaction cost on the bar the position flips.
+            equity *= (1.0 - cost)
+
+        bar_return = bar_returns[index] if position == 1 else 0.0
+        equity *= (1.0 + bar_return)
+        strategy_returns.append(bar_return)
+
+        if position == 1:
+            invested_bars += 1
+
+        equity_curve.append({"ts": timestamps[index], "equity": round(equity, 2)})
+        prev_position = position
+
+    metrics = _compute_metrics(
+        equity_curve=equity_curve,
+        strategy_returns=strategy_returns,
+        trades=trades,
+        invested_bars=invested_bars,
+        total_bars=len(closes) - 1,
+        interval=interval,
+        starting_equity=starting_equity,
+    )
+
+    return {"equityCurve": equity_curve, "trades": trades, "metrics": metrics}
+
+
+def _compute_metrics(equity_curve, strategy_returns, trades, invested_bars,
+                     total_bars, interval, starting_equity):
+    equity_values = [point["equity"] for point in equity_curve]
+    final_equity = equity_values[-1]
+    total_return = (final_equity / starting_equity - 1.0) * 100.0
+
+    factor = bars_per_year(interval)
+    n = len(strategy_returns)
+    years = n / factor if factor else 0.0
+
+    cagr = ((final_equity / starting_equity) ** (1.0 / years) - 1.0) * 100.0 if years > 0 else 0.0
+
+    if n > 1:
+        mean = sum(strategy_returns) / n
+        variance = sum((r - mean) ** 2 for r in strategy_returns) / (n - 1)
+        std = math.sqrt(variance)
+    else:
+        mean = strategy_returns[0] if strategy_returns else 0.0
+        std = 0.0
+
+    ann_vol = std * math.sqrt(factor) * 100.0
+    sharpe = (mean / std * math.sqrt(factor)) if std > 0 else 0.0
+
+    max_dd = _max_drawdown(equity_values)
+
+    # Win rate over completed round-trips (entry buy -> exit sell).
+    wins = 0
+    round_trips = 0
+    entry_price = None
+
+    for trade in trades:
+        if trade["side"] == "buy":
+            entry_price = trade["price"]
+        elif trade["side"] == "sell" and entry_price is not None:
+            round_trips += 1
+
+            if trade["price"] > entry_price:
+                wins += 1
+
+            entry_price = None
+
+    win_rate = (wins / round_trips * 100.0) if round_trips else 0.0
+    exposure = (invested_bars / total_bars * 100.0) if total_bars else 0.0
+
+    return {
+        "totalReturnPct": round(total_return, 2),
+        "cagrPct": round(cagr, 2),
+        "annVolPct": round(ann_vol, 2),
+        "sharpe": round(sharpe, 2),
+        "maxDrawdownPct": round(max_dd, 2),
+        "winRate": round(win_rate, 1),
+        "numTrades": len(trades),
+        "exposurePct": round(exposure, 1),
+        "finalEquity": round(final_equity, 2),
+    }

backtestchat/strategy/indicators.py

@@ -0,0 +1,186 @@
+"""Pure technical-indicator functions (no I/O).
+
+All return a list aligned to the input length, with `None` during the warmup
+period (before the indicator has enough data). Inputs are plain lists of floats.
+"""
+
+import math
+
+
+def sma(values, window):
+    """Trailing simple moving average; None for indices < window-1."""
+    out = []
+    running = 0.0
+
+    for index, value in enumerate(values):
+        running += value
+
+        if index >= window:
+            running -= values[index - window]
+
+        out.append(running / window if index >= window - 1 else None)
+
+    return out
+
+
+def ema(values, window):
+    """Exponential moving average seeded with the SMA of the first `window`."""
+    out = [None] * len(values)
+
+    if len(values) < window:
+        return out
+
+    k = 2.0 / (window + 1)
+    seed = sum(values[:window]) / window
+    out[window - 1] = seed
+    prev = seed
+
+    for index in range(window, len(values)):
+        prev = values[index] * k + prev * (1 - k)
+        out[index] = prev
+
+    return out
+
+
+def rolling_std(values, window):
+    """Trailing population standard deviation; None during warmup."""
+    out = []
+
+    for index in range(len(values)):
+        if index < window - 1:
+            out.append(None)
+            continue
+
+        window_slice = values[index - window + 1 : index + 1]
+        mean = sum(window_slice) / window
+        variance = sum((v - mean) ** 2 for v in window_slice) / window
+        out.append(math.sqrt(variance))
+
+    return out
+
+
+def rolling_max(values, window):
+    out = []
+    for index in range(len(values)):
+        if index < window - 1:
+            out.append(None)
+        else:
+            out.append(max(values[index - window + 1 : index + 1]))
+    return out
+
+
+def rolling_min(values, window):
+    out = []
+    for index in range(len(values)):
+        if index < window - 1:
+            out.append(None)
+        else:
+            out.append(min(values[index - window + 1 : index + 1]))
+    return out
+
+
+def rsi(closes, period):
+    """Wilder's RSI; None until `period` returns are available."""
+    out = [None] * len(closes)
+
+    if len(closes) <= period:
+        return out
+
+    gains = 0.0
+    losses = 0.0
+
+    for index in range(1, period + 1):
+        change = closes[index] - closes[index - 1]
+        gains += max(change, 0.0)
+        losses += max(-change, 0.0)
+
+    avg_gain = gains / period
+    avg_loss = losses / period
+    out[period] = _rsi_value(avg_gain, avg_loss)
+
+    for index in range(period + 1, len(closes)):
+        change = closes[index] - closes[index - 1]
+        gain = max(change, 0.0)
+        loss = max(-change, 0.0)
+        avg_gain = (avg_gain * (period - 1) + gain) / period
+        avg_loss = (avg_loss * (period - 1) + loss) / period
+        out[index] = _rsi_value(avg_gain, avg_loss)
+
+    return out
+
+
+def _rsi_value(avg_gain, avg_loss):
+    if avg_loss == 0:
+        return 100.0
+    rs = avg_gain / avg_loss
+    return 100.0 - 100.0 / (1.0 + rs)
+
+
+def macd(closes, fast, slow, signal):
+    """Return (macd_line, signal_line), each aligned with None during warmup."""
+    ema_fast = ema(closes, fast)
+    ema_slow = ema(closes, slow)
+
+    macd_line = [
+        (ema_fast[i] - ema_slow[i]) if (ema_fast[i] is not None and ema_slow[i] is not None) else None
+        for i in range(len(closes))
+    ]
+
+    # Signal line = EMA of the macd_line over its non-None tail.
+    valid = [v for v in macd_line if v is not None]
+    signal_tail = ema(valid, signal)
+
+    signal_line = [None] * len(closes)
+    first_valid = next((i for i, v in enumerate(macd_line) if v is not None), None)
+
+    if first_valid is not None:
+        for offset, value in enumerate(signal_tail):
+            signal_line[first_valid + offset] = value
+
+    return macd_line, signal_line
+
+
+def roc(closes, period):
+    """Rate of change (%) over `period` bars; None during warmup."""
+    out = [None] * len(closes)
+
+    for index in range(period, len(closes)):
+        prev = closes[index - period]
+        if prev:
+            out[index] = (closes[index] / prev - 1.0) * 100.0
+
+    return out
+
+
+def true_range(highs, lows, closes):
+    """True range per bar; index 0 uses high-low."""
+    out = [highs[0] - lows[0]] if highs else []
+
+    for index in range(1, len(highs)):
+        prev_close = closes[index - 1]
+        out.append(max(
+            highs[index] - lows[index],
+            abs(highs[index] - prev_close),
+            abs(lows[index] - prev_close),
+        ))
+
+    return out
+
+
+def atr(highs, lows, closes, window):
+    """Wilder's ATR (RMA of true range); None during warmup."""
+    tr = true_range(highs, lows, closes)
+    out = [None] * len(tr)
+
+    if len(tr) < window:
+        return out
+
+    seed = sum(tr[:window]) / window
+    out[window - 1] = seed
+    prev = seed
+
+    for index in range(window, len(tr)):
+        prev = (prev * (window - 1) + tr[index]) / window
+        out[index] = prev
+
+    return out

backtestchat/strategy/registry.py

@@ -0,0 +1,272 @@
+"""Strategy registry - the catalog of single-signal long/flat strategies.
+
+Each entry declares:
+  - label / description (for display + the agent catalog)
+  - param_schema (defaults + bounds; also rendered into the catalog)
+  - validate(params) -> normalized params dict (fills defaults, enforces bounds)
+  - signal_fn(bars, params) -> [0|1] per bar
+  - series_fn(bars, params) -> ([0|1] per bar, {name: per-bar indicator series})
+  - warmup(params) -> int (min bars before the first valid signal)
+  - format_label(params) -> human label (e.g. "RSI (14, 30/70)")
+
+Adding a strategy is a registry entry + a signal function in signals.py; the
+engine and services look everything up by strategy_type.
+"""
+
+from backtestchat.strategy import signals
+
+
+def _int(params, key, default):
+    return int(params.get(key, default)) if params.get(key) is not None else default
+
+
+def _float(params, key, default):
+    return float(params.get(key, default)) if params.get(key) is not None else default
+
+
+# --- validators (return normalized param dicts) --------------------------------
+
+def _v_buy_hold(p):
+    return {}
+
+
+def _v_crossover(p, fast_def, slow_def):
+    fast = _int(p, "fast", fast_def)
+    slow = _int(p, "slow", slow_def)
+    if fast < 2 or slow < 3:
+        raise ValueError("fast must be >= 2 and slow must be >= 3.")
+    if fast >= slow:
+        raise ValueError("fast window must be smaller than slow window.")
+    return {"fast": fast, "slow": slow}
+
+
+def _v_macd(p):
+    fast = _int(p, "fast", 12)
+    slow = _int(p, "slow", 26)
+    signal = _int(p, "signal", 9)
+    if fast < 2 or slow <= fast or signal < 1:
+        raise ValueError("macd needs fast >= 2, slow > fast, signal >= 1.")
+    return {"fast": fast, "slow": slow, "signal": signal}
+
+
+def _v_rsi(p):
+    period = _int(p, "period", 14)
+    lower = _float(p, "lower", 30.0)
+    upper = _float(p, "upper", 70.0)
+    if period < 2 or not (0 < lower < upper < 100):
+        raise ValueError("rsi needs period >= 2 and 0 < lower < upper < 100.")
+    return {"period": period, "lower": lower, "upper": upper}
+
+
+def _v_bollinger(p):
+    window = _int(p, "window", 20)
+    num_std = _float(p, "num_std", 2.0)
+    if window < 3 or num_std <= 0:
+        raise ValueError("bollinger needs window >= 3 and num_std > 0.")
+    return {"window": window, "num_std": num_std}
+
+
+def _v_roc(p):
+    period = _int(p, "period", 63)
+    if period < 2:
+        raise ValueError("roc needs period >= 2.")
+    return {"period": period}
+
+
+def _v_price_above_sma(p):
+    window = _int(p, "window", 200)
+    if window < 2:
+        raise ValueError("price_above_sma needs window >= 2.")
+    return {"window": window}
+
+
+def _v_donchian(p):
+    entry = _int(p, "entry", 20)
+    exit_w = _int(p, "exit", 10)
+    if entry < 2 or exit_w < 2:
+        raise ValueError("donchian needs entry >= 2 and exit >= 2.")
+    return {"entry": entry, "exit": exit_w}
+
+
+def _v_stochastic(p):
+    k = _int(p, "k", 14)
+    d = _int(p, "d", 3)
+    if k < 2 or d < 1:
+        raise ValueError("stochastic needs k >= 2 and d >= 1.")
+    return {"k": k, "d": d}
+
+
+def _v_atr_channel(p):
+    window = _int(p, "window", 20)
+    mult = _float(p, "mult", 2.0)
+    if window < 2 or mult <= 0:
+        raise ValueError("atr_channel needs window >= 2 and mult > 0.")
+    return {"window": window, "mult": mult}
+
+
+STRATEGY_REGISTRY = {
+    "buy_hold": {
+        "label": "Buy & Hold",
+        "description": "Always fully invested. Market baseline.",
+        "param_schema": {},
+        "signal_fn": signals.buy_hold_signals,
+        "series_fn": signals.buy_hold_series,
+        "validate": _v_buy_hold,
+        "warmup": lambda p: 1,
+        "format_label": lambda p: "Buy & Hold",
+    },
+    "ma_crossover": {
+        "label": "SMA Crossover",
+        "description": "Long when the fast SMA is above the slow SMA. params: fast (50), slow (200).",
+        "param_schema": {"fast": {"default": 50}, "slow": {"default": 200}},
+        "signal_fn": signals.ma_crossover_signals,
+        "series_fn": signals.ma_crossover_series,
+        "validate": lambda p: _v_crossover(p, 50, 200),
+        "warmup": lambda p: p["slow"],
+        "format_label": lambda p: f"SMA Crossover ({p['fast']}/{p['slow']})",
+    },
+    "ema_crossover": {
+        "label": "EMA Crossover",
+        "description": "Long when the fast EMA is above the slow EMA. params: fast (12), slow (26).",
+        "param_schema": {"fast": {"default": 12}, "slow": {"default": 26}},
+        "signal_fn": signals.ema_crossover_signals,
+        "series_fn": signals.ema_crossover_series,
+        "validate": lambda p: _v_crossover(p, 12, 26),
+        "warmup": lambda p: p["slow"] * 3,
+        "format_label": lambda p: f"EMA Crossover ({p['fast']}/{p['slow']})",
+    },
+    "macd": {
+        "label": "MACD",
+        "description": "Long when the MACD line is above its signal line. params: fast (12), slow (26), signal (9).",
+        "param_schema": {"fast": {"default": 12}, "slow": {"default": 26}, "signal": {"default": 9}},
+        "signal_fn": signals.macd_signals,
+        "series_fn": signals.macd_series,
+        "validate": _v_macd,
+        "warmup": lambda p: p["slow"] * 3 + p["signal"],
+        "format_label": lambda p: f"MACD ({p['fast']}/{p['slow']}/{p['signal']})",
+    },
+    "rsi": {
+        "label": "RSI",
+        "description": "Mean-reversion: go long when RSI falls below lower, exit when it rises above upper. params: period (14), lower (30), upper (70).",
+        "param_schema": {"period": {"default": 14}, "lower": {"default": 30}, "upper": {"default": 70}},
+        "signal_fn": signals.rsi_signals,
+        "series_fn": signals.rsi_series,
+        "validate": _v_rsi,
+        "warmup": lambda p: p["period"] + 1,
+        "format_label": lambda p: f"RSI ({p['period']}, {int(p['lower'])}/{int(p['upper'])})",
+    },
+    "bollinger": {
+        "label": "Bollinger Bands",
+        "description": "Mean-reversion: go long when price closes below the lower band, exit when it closes above the middle band. params: window (20), num_std (2).",
+        "param_schema": {"window": {"default": 20}, "num_std": {"default": 2}},
+        "signal_fn": signals.bollinger_signals,
+        "series_fn": signals.bollinger_series,
+        "validate": _v_bollinger,
+        "warmup": lambda p: p["window"],
+        "format_label": lambda p: f"Bollinger ({p['window']}, {p['num_std']:g}sd)",
+    },
+    "roc": {
+        "label": "Momentum (ROC)",
+        "description": "Long when the rate of change over the period is positive. params: period (63).",
+        "param_schema": {"period": {"default": 63}},
+        "signal_fn": signals.roc_signals,
+        "series_fn": signals.roc_series,
+        "validate": _v_roc,
+        "warmup": lambda p: p["period"],
+        "format_label": lambda p: f"Momentum ROC ({p['period']})",
+    },
+    "price_above_sma": {
+        "label": "Price vs SMA",
+        "description": "Trend filter: long when price is above its SMA. params: window (200).",
+        "param_schema": {"window": {"default": 200}},
+        "signal_fn": signals.price_above_sma_signals,
+        "series_fn": signals.price_above_sma_series,
+        "validate": _v_price_above_sma,
+        "warmup": lambda p: p["window"],
+        "format_label": lambda p: f"Price > SMA ({p['window']})",
+    },
+    "donchian_breakout": {
+        "label": "Donchian Breakout",
+        "description": "Trend breakout: long when price breaks above the prior entry-day high, exit below the prior exit-day low. params: entry (20), exit (10).",
+        "param_schema": {"entry": {"default": 20}, "exit": {"default": 10}},
+        "signal_fn": signals.donchian_breakout_signals,
+        "series_fn": signals.donchian_breakout_series,
+        "validate": _v_donchian,
+        "warmup": lambda p: max(p["entry"], p["exit"]),
+        "format_label": lambda p: f"Donchian ({p['entry']}/{p['exit']})",
+    },
+    "stochastic": {
+        "label": "Stochastic Oscillator",
+        "description": "Long when %K is above %D. params: k (14), d (3).",
+        "param_schema": {"k": {"default": 14}, "d": {"default": 3}},
+        "signal_fn": signals.stochastic_signals,
+        "series_fn": signals.stochastic_series,
+        "validate": _v_stochastic,
+        "warmup": lambda p: p["k"] + p["d"],
+        "format_label": lambda p: f"Stochastic ({p['k']}/{p['d']})",
+    },
+    "atr_channel": {
+        "label": "ATR Channel (Keltner)",
+        "description": "Breakout: long when price closes above EMA + mult*ATR, exit when it closes below the EMA. params: window (20), mult (2).",
+        "param_schema": {"window": {"default": 20}, "mult": {"default": 2}},
+        "signal_fn": signals.atr_channel_signals,
+        "series_fn": signals.atr_channel_series,
+        "validate": _v_atr_channel,
+        "warmup": lambda p: p["window"] + 1,
+        "format_label": lambda p: f"ATR Channel ({p['window']}, {p['mult']:g}x)",
+    },
+}
+
+
+def is_supported_strategy(strategy_type):
+    return strategy_type in STRATEGY_REGISTRY
+
+
+def supported_strategies():
+    return list(STRATEGY_REGISTRY.keys())
+
+
+def get_signal_fn(strategy_type):
+    entry = STRATEGY_REGISTRY.get(strategy_type)
+    if not entry:
+        raise ValueError(f"Unsupported strategy: {strategy_type}")
+    return entry["signal_fn"]
+
+
+def get_series_fn(strategy_type):
+    entry = STRATEGY_REGISTRY.get(strategy_type)
+    if not entry:
+        raise ValueError(f"Unsupported strategy: {strategy_type}")
+    return entry["series_fn"]
+
+
+def validate_params(strategy_type, params):
+    entry = STRATEGY_REGISTRY.get(strategy_type)
+    if not entry:
+        raise ValueError(f"Unsupported strategy: {strategy_type}")
+    return entry["validate"](params or {})
+
+
+def strategy_warmup(strategy_type, params):
+    entry = STRATEGY_REGISTRY.get(strategy_type)
+    if not entry:
+        return 1
+    return entry["warmup"](params)
+
+
+def strategy_label(strategy_type, params=None):
+    entry = STRATEGY_REGISTRY.get(strategy_type)
+    if not entry:
+        return strategy_type
+    try:
+        return entry["format_label"](params or entry["validate"]({}))
+    except Exception:
+        return entry["label"]
+
+
+def describe_strategies():
+    """Catalog text for the agent prompt."""
+    lines = []
+    for key, entry in STRATEGY_REGISTRY.items():
+        lines.append(f"- {key}: {entry['description']}")
+    return "\n".join(lines)