aether-quant 0.0.1__py3-none-any.whl

evaluation/limit_fill_simulator.py

@@ -0,0 +1,152 @@
+"""V5.3.1 (development/Problems.md #34/#96) - an offline, counterfactual
+answer to "how often would a real limit order actually fill" without a
+live Lean run: for every (ticker, date) row in an existing dataset, this
+computes a limit price the exact same way main.py's real order placement
+does (execution.order_gate.resolve_limit_price(), the SAME pure function,
+not a re-derived approximation), then scans that ticker's own next
+`unfilled_timeout_bars` rows' high/low columns to determine whether a real
+Lean fill engine plausibly would have crossed it.
+
+APPROXIMATION, NOT A REPLAY (read before trusting these numbers): this
+simulates a signal firing on EVERY row, independent of whether main.py's
+book/gates would have actually placed an order that day - it measures "if
+an order were placed here, would it fill", not "how many of the real
+orders in a given backtest filled" (development/Problems.md #34/#96's own
+real order-events.json evidence is the ground truth for the latter
+question; this module is deliberately a different, complementary
+question). It also has no intrabar depth/tick data (only daily OHLC), so
+it can only ever answer "did price trade through the limit", never
+simulate a genuine partial fill - the same historical-bar-CSV ceiling
+that makes PartiallyFilled unverifiable offline at all (see #34/#96's
+verification notes)."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from execution.order_gate import resolve_limit_price
+
+
+def simulate_limit_fills(
+    dataset: pd.DataFrame,
+    *,
+    unfilled_timeout_bars: int,
+    offset_multiplier: float = 1.0,
+    ticker_column: str = "ticker",
+    date_column: str = "date",
+    security_type_column: str = "security_type",
+) -> dict:
+    """Per ticker (grouped, sorted by date_column): for every row with at
+    least `unfilled_timeout_bars` rows of data remaining for that ticker
+    (rows too close to the end of a ticker's history are EXCLUDED from the
+    denominator entirely, not counted as a timeout - a thin-data edge
+    effect, not a real timeout, matching calibrate_book_confidence_spread()'s
+    own "excluded, not counted as 0" convention), simulates BOTH a buy and
+    a sell limit order (the real book trades both long and short, so
+    simulating only one side would under-cover the calibration question).
+
+    A buy fills the first bar (within the timeout window) whose `low`
+    reaches at/below the buy limit price; a sell fills the first bar whose
+    `high` reaches at/above the sell limit price - otherwise it's a
+    timeout. `liquidity_spread_proxy` (already in ml/datasets/*.csv, the
+    same column execution.order_gate.resolve_limit_price() expects as
+    spread_fraction) supplies the spread input.
+
+    Returns {"overall": {...}, "by_asset_class": {security_type: {...}},
+    "by_side": {"buy": {...}, "sell": {...}}}, each a dict of
+    {"num_signals", "fill_rate", "timeout_rate", "mean_bars_to_fill"}.
+    An empty/all-thin dataset returns all-zero stats, never raises."""
+    records: list[dict] = []
+
+    has_security_type = security_type_column in dataset.columns
+    for _ticker, group in dataset.groupby(ticker_column, sort=False):
+        group = group.sort_values(date_column).reset_index(drop=True)
+        closes = group["close"].to_numpy()
+        highs = group["high"].to_numpy()
+        lows = group["low"].to_numpy()
+        spreads = group["liquidity_spread_proxy"].to_numpy()
+        security_types = group[security_type_column].to_numpy() if has_security_type else [None] * len(group)
+        num_rows = len(group)
+
+        for i in range(num_rows):
+            if i + unfilled_timeout_bars >= num_rows:
+                continue  # too close to the end of this ticker's data - excluded, not a timeout
+            reference_price = float(closes[i])
+            raw_spread = spreads[i]
+            spread_fraction = 0.0 if pd.isna(raw_spread) else float(raw_spread)
+            security_type = security_types[i]
+
+            for is_buy in (True, False):
+                limit_price = resolve_limit_price(reference_price, spread_fraction, is_buy, offset_multiplier)
+                bars_to_fill = None
+                for offset in range(1, unfilled_timeout_bars + 1):
+                    j = i + offset
+                    crossed = lows[j] <= limit_price if is_buy else highs[j] >= limit_price
+                    if crossed:
+                        bars_to_fill = offset
+                        break
+                records.append(
+                    {
+                        "side": "buy" if is_buy else "sell",
+                        "security_type": security_type,
+                        "filled": bars_to_fill is not None,
+                        "bars_to_fill": bars_to_fill,
+                    }
+                )
+
+    return {
+        "overall": _summarize_fill_records(records),
+        "by_asset_class": {
+            str(security_type): _summarize_fill_records(group_records)
+            for security_type, group_records in _group_by(records, "security_type").items()
+        },
+        "by_side": {
+            side: _summarize_fill_records(group_records) for side, group_records in _group_by(records, "side").items()
+        },
+    }
+
+
+def sweep_limit_fill_offsets(
+    dataset: pd.DataFrame,
+    *,
+    unfilled_timeout_bars: int,
+    offset_multipliers: list[float],
+    ticker_column: str = "ticker",
+    date_column: str = "date",
+    security_type_column: str = "security_type",
+) -> dict:
+    """Runs simulate_limit_fills() once per offset_multiplier - calibration
+    insight into how a more/less passive limit placement trades off fill
+    rate vs. price improvement. Returns {str(multiplier): result}."""
+    return {
+        str(multiplier): simulate_limit_fills(
+            dataset,
+            unfilled_timeout_bars=unfilled_timeout_bars,
+            offset_multiplier=multiplier,
+            ticker_column=ticker_column,
+            date_column=date_column,
+            security_type_column=security_type_column,
+        )
+        for multiplier in offset_multipliers
+    }
+
+
+def _group_by(records: list[dict], key: str) -> dict:
+    groups: dict = {}
+    for record in records:
+        groups.setdefault(record[key], []).append(record)
+    return groups
+
+
+def _summarize_fill_records(records: list[dict]) -> dict:
+    num_signals = len(records)
+    if num_signals == 0:
+        return {"num_signals": 0, "fill_rate": 0.0, "timeout_rate": 0.0, "mean_bars_to_fill": None}
+    num_filled = sum(1 for record in records if record["filled"])
+    bars_to_fill_values = [record["bars_to_fill"] for record in records if record["bars_to_fill"] is not None]
+    return {
+        "num_signals": num_signals,
+        "fill_rate": num_filled / num_signals,
+        "timeout_rate": (num_signals - num_filled) / num_signals,
+        "mean_bars_to_fill": (sum(bars_to_fill_values) / len(bars_to_fill_values)) if bars_to_fill_values else None,
+    }

evaluation/model_predictions.py

@@ -0,0 +1,192 @@
+"""Loads an exported model (ml/{multitask,sequence}_model.json) plus the
+active dataset, and runs every row through inference/exported_model.py -
+the EXACT torch-free interpreter main.py's live decision path uses - to
+produce a predicted-<head> column. Deliberately its own module, not
+train.py: train.py imports torch, and `aq evaluate` must stay fast to
+start for commands that never need training-time code (this package's
+torch-free contract - see evaluation/__init__.py's docstring).
+
+Because this reuses inference/exported_model.py verbatim (not a
+re-derived approximation), `aq evaluate --rank-book` reports the SAME
+numbers a live/backtest run would produce from the same artifacts -
+including any live quirk in those artifacts (e.g. Problems.md #73's
+sigmoid-vs-raw mismatch), which is the point: this is meant to be an
+offline mirror of live behavior, not a separate idealized model.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from inference.exported_model import (
+    resolve_sequence_window_size,
+    run_exported_multitask_model,
+    run_exported_sequence_multitask_model,
+)
+
+
+def build_sequence_windows(
+    dataset: pd.DataFrame,
+    model_input_names: list[str],
+    window_size: int,
+    ticker_column: str = "ticker",
+) -> np.ndarray:
+    """Torch-free port of train.py::build_sequence_tensor_dataset() - same
+    algorithm (each ticker's own trailing window, left-padded with zeros
+    for rows with fewer than window_size preceding rows, row-order-aligned
+    with `dataset`), deliberately duplicated rather than imported since
+    train.py pulls in torch and this module must stay import-light.
+    `dataset` must already be sorted the way build_feature_dataset() leaves
+    it (each ticker's own rows in chronological order) - the same
+    precondition train.py's version documents.
+
+    float32, not float64 (V5.1 Phase 5, Problems.md #83) - halves peak
+    memory for no correctness cost: every consumer (run_exported_sequence_
+    multitask_model()) takes `sequence: list[list[float]]` and converts via
+    .tolist() before use, so the underlying numpy dtype is invisible to it
+    either way. Matches train.py::build_sequence_tensor_dataset()'s own
+    dtype, which was already float32."""
+    feature_matrix = dataset[model_input_names].to_numpy(dtype=np.float32)
+    tickers = dataset[ticker_column].to_numpy()
+
+    windows = np.zeros((len(dataset), window_size, len(model_input_names)), dtype=np.float32)
+    positions_by_ticker: dict[object, list[int]] = {}
+    for position, ticker in enumerate(tickers):
+        positions_by_ticker.setdefault(ticker, []).append(position)
+
+    for positions in positions_by_ticker.values():
+        for index_within_ticker, position in enumerate(positions):
+            window_start = max(0, index_within_ticker + 1 - window_size)
+            window_positions = positions[window_start : index_within_ticker + 1]
+            window_values = feature_matrix[window_positions]
+            windows[position, -len(window_values) :, :] = window_values
+
+    return windows
+
+
+def select_context_date_range(
+    dataset: pd.DataFrame,
+    recorded_dates: list[str],
+    *,
+    window_size: int,
+    ticker_column: str = "ticker",
+    date_column: str = "date",
+) -> tuple[str, str]:
+    """V5.2.2 (development/Problems.md) - computes the inclusive
+    `(min_date, max_date)` date-string bounds a caller must keep every
+    row for (per ticker, in `dataset`'s own row order) before restricting
+    the dataset to a specific set of `recorded_dates` and still getting
+    CORRECT `build_sequence_windows()` output for those dates.
+
+    GUARDRAIL: `build_sequence_windows()` builds each ticker's trailing
+    window from ORDINAL ROW POSITION within whatever frame it's given,
+    not from calendar dates - it has no way to know rows were dropped.
+    Naively filtering `dataset` down to only `recorded_dates` before
+    calling it does not raise; it silently builds each window from
+    whichever OTHER kept rows happen to be ordinally adjacent (e.g. 10
+    calendar days apart instead of 1), producing wrong predictions with
+    no error. This function exists so a caller can safely narrow a large
+    dataset to just the date range a reconciliation actually needs
+    (`aq evaluate --reconcile-book-history`'s whole reason for existing)
+    without corrupting sequence-model context: keep every row inside
+    `[min(recorded_dates), max(recorded_dates)]` UNCHANGED, plus enough
+    additional rows per ticker immediately preceding that span (by row
+    position, not calendar-day subtraction, since non-trading days never
+    appear in `dataset` to begin with) to fully support a `window_size`
+    trailing window for the earliest recorded date. Only rows entirely
+    outside the returned bounds may be safely dropped.
+
+    Per ticker: finds the first row at/after `min(recorded_dates)`, then
+    walks back `window_size` positions (mirroring `build_sequence_windows()`'s
+    own `max(0, index_within_ticker + 1 - window_size)` formula exactly)
+    to find that ticker's own earliest-needed date. The overall
+    `min_date` returned is the EARLIEST such date across all tickers, so
+    every ticker's window is fully supported, not just the first one
+    encountered. A ticker with no rows at/after `min(recorded_dates)` at
+    all is skipped (nothing to support for it).
+
+    Raises `ValueError` if `recorded_dates` is empty - there is no
+    context range to compute without at least one target date."""
+    if not recorded_dates:
+        raise ValueError("select_context_date_range() requires at least one recorded date")
+
+    target_min = min(recorded_dates)
+    target_max = max(recorded_dates)
+
+    earliest_needed_dates: list[str] = []
+    for _ticker, ticker_frame in dataset.groupby(ticker_column, sort=False):
+        ticker_dates = ticker_frame[date_column].tolist()
+        boundary_index = next((i for i, d in enumerate(ticker_dates) if d >= target_min), None)
+        if boundary_index is None:
+            continue
+        lookback_start = max(0, boundary_index + 1 - window_size)
+        earliest_needed_dates.append(ticker_dates[lookback_start])
+
+    min_date = min(earliest_needed_dates) if earliest_needed_dates else target_min
+    return min_date, target_max
+
+
+def predict_multitask_head(
+    dataset: pd.DataFrame, model_export: dict, feature_names: list[str], head: str
+) -> np.ndarray:
+    """One run_exported_multitask_model() call per row - the flat-MLP
+    trunk needs no windowing, unlike the sequence model below."""
+    predictions = np.full(len(dataset), np.nan, dtype=np.float64)
+    feature_matrix = dataset[feature_names].to_numpy(dtype=np.float64)
+    for row_index in range(len(dataset)):
+        outputs = run_exported_multitask_model(model_export, feature_matrix[row_index].tolist())
+        predictions[row_index] = outputs.get(head, np.nan)
+    return predictions
+
+
+def predict_sequence_head(
+    dataset: pd.DataFrame,
+    model_export: dict,
+    feature_names: list[str],
+    head: str,
+    *,
+    sequence_feature_schema: dict | None = None,
+    configured_window_size: int = 30,
+    ticker_column: str = "ticker",
+) -> np.ndarray:
+    """Builds each row's trailing window via build_sequence_windows() then
+    runs run_exported_sequence_multitask_model() per row. window_size comes
+    from resolve_sequence_window_size() - the trained model's OWN schema
+    wins over any configured default, the same shape-mismatch-avoidance
+    contract main.py's live sequence-model path already follows."""
+    window_size = resolve_sequence_window_size(sequence_feature_schema, configured_window_size)
+    windows = build_sequence_windows(dataset, feature_names, window_size, ticker_column)
+    predictions = np.full(len(dataset), np.nan, dtype=np.float64)
+    for row_index in range(len(dataset)):
+        outputs = run_exported_sequence_multitask_model(model_export, windows[row_index].tolist())
+        predictions[row_index] = outputs.get(head, np.nan)
+    return predictions
+
+
+def predict_head(
+    dataset: pd.DataFrame,
+    model_export: dict,
+    feature_names: list[str],
+    head: str,
+    *,
+    model_kind: str,
+    sequence_feature_schema: dict | None = None,
+    configured_window_size: int = 30,
+    ticker_column: str = "ticker",
+) -> np.ndarray:
+    """Single dispatch point for `aq evaluate` - model_kind in
+    {"multitask", "sequence"} picks the right predictor above. Any other
+    value raises ValueError (a genuinely programmer-facing error, not a
+    runtime degradation case - unlike every other function in this
+    package, this one is not on main.py's live path)."""
+    if model_kind == "multitask":
+        return predict_multitask_head(dataset, model_export, feature_names, head)
+    if model_kind == "sequence":
+        return predict_sequence_head(
+            dataset, model_export, feature_names, head,
+            sequence_feature_schema=sequence_feature_schema,
+            configured_window_size=configured_window_size,
+            ticker_column=ticker_column,
+        )
+    raise ValueError(f"unknown model_kind {model_kind!r} - expected 'multitask' or 'sequence'")

evaluation/monte_carlo.py

@@ -0,0 +1,161 @@
+"""V5.3.8 - Monte Carlo simulation testing layer (pure core).
+
+Resamples the offline rank book's daily NET return series into N
+alternative equity histories so risk can be stated as a DISTRIBUTION
+instead of a single path: percentile bands for total return / Sharpe /
+max drawdown, probability of loss, and the average compounded curve that
+the README visual draws as its red center line.
+
+Two resampling methods:
+- "block" (default): stationary block bootstrap - contiguous chunks of
+  `block_size` days are resampled with replacement, preserving the
+  short-horizon autocorrelation/volatility clustering a naive i.i.d.
+  shuffle would erase.
+- "iid": element-wise resampling - the classical Monte Carlo baseline.
+
+Pure: numpy only, no I/O, no torch, deterministic given (`seed`, inputs).
+The heavy per-run curve matrix is returned DOWNSAMPLED (`n_plot_points`)
+so callers can persist it without multi-megabyte payloads.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+TRADING_DAYS_PER_YEAR = 252
+
+
+def _max_drawdown(equity: np.ndarray) -> float:
+    peak = np.maximum.accumulate(equity)
+    drawdown = 1.0 - equity / peak
+    return float(drawdown.max()) if drawdown.size else 0.0
+
+
+def _annualized_sharpe(sampled_returns: np.ndarray) -> float:
+    if sampled_returns.size < 2:
+        return 0.0
+    std = sampled_returns.std(ddof=1)
+    if std == 0:
+        return 0.0
+    return float(sampled_returns.mean() / std * np.sqrt(TRADING_DAYS_PER_YEAR))
+
+
+def _resample_indices(n: int, block_size: int, method: str, rng: np.random.Generator) -> np.ndarray:
+    if method == "iid":
+        return rng.integers(0, n, n)
+    n_blocks = int(np.ceil(n / block_size))
+    starts = rng.integers(0, n, size=n_blocks)
+    idx = (starts[:, None] + np.arange(block_size)[None, :]).ravel()
+    return idx[:n] % n
+
+
+def _percentiles(values: np.ndarray) -> dict[str, float]:
+    pct = np.percentile(values, [5, 25, 50, 75, 95])
+    keys = ["p5", "p25", "p50", "p75", "p95"]
+    return {k: round(float(v), 6) for k, v in zip(keys, pct)}
+
+
+def run_monte_carlo(
+    per_date_net_returns,
+    *,
+    n_runs: int = 1000,
+    block_size: int = 20,
+    seed: int = 42,
+    method: str = "block",
+    n_plot_points: int = 500,
+) -> dict[str, Any]:
+    """Runs the bootstrap and returns a self-describing result dict:
+
+    {"config": {...},
+     "status": "OK" | "SKIPPED: <reason>",
+     "avg_curve": [...],                       # downsampled, red line
+     "pct_band": {"p5": [...], "p25": [...], "p75": [...], "p95": [...]},
+     "runs_curves": np.ndarray (n_runs x points),   # downsampled, for PNG
+     "final_return_pct": {...percentiles}, "sharpe": {...}, "max_drawdown": {...},
+     "prob_negative_return": float, "best_run_total_return": ..., "worst_run_total_return": ...}
+
+    Equity curves are compounded from resampled daily returns and start at
+    1.0. The average curve is the element-wise MEAN over all runs (the red
+    line), NOT the mean of final values.
+    """
+    config = {
+        "n_runs": int(n_runs),
+        "block_size": int(block_size),
+        "seed": int(seed),
+        "method": str(method),
+        "trading_days_per_year": TRADING_DAYS_PER_YEAR,
+    }
+    empty = {
+        "config": config,
+        "status": "",
+        "avg_curve": [],
+        "pct_band": {},
+        "final_return_pct": {},
+        "sharpe": {},
+        "max_drawdown": {},
+        "prob_negative_return": None,
+        "best_run_total_return": None,
+        "worst_run_total_return": None,
+    }
+    returns = np.asarray(list(per_date_net_returns), dtype=float)
+    returns = returns[~np.isnan(returns)]
+    if returns.size < 30:
+        empty["status"] = f"SKIPPED: need >= 30 daily returns, got {returns.size}"
+        return empty
+    if n_runs < 1:
+        empty["status"] = "SKIPPED: n_runs < 1"
+        return empty
+    if method not in ("block", "iid"):
+        empty["status"] = f"SKIPPED: unknown method {method}"
+        return empty
+
+    n = returns.size
+    rng = np.random.default_rng(seed)
+
+    plot_points = min(n, max(int(n_plot_points), 2))
+    plot_idx = np.linspace(0, n - 1, plot_points).astype(int)
+
+    curves = np.empty((int(n_runs), plot_points), dtype=float)
+    final_returns = np.empty(int(n_runs))
+    sharpes = np.empty(int(n_runs))
+    drawdowns = np.empty(int(n_runs))
+
+    for run in range(int(n_runs)):
+        sampled = returns[_resample_indices(n, block_size, method, rng)]
+        equity = np.cumprod(1.0 + sampled)
+        sharpes[run] = _annualized_sharpe(sampled)
+        drawdowns[run] = _max_drawdown(equity)
+        final_returns[run] = equity[-1] - 1.0
+        curves[run] = equity[plot_idx]
+
+    # Normalize every plotted curve to start exactly at 1.0 for readability.
+    starts = curves[:, [0]]
+    starts[starts == 0] = 1.0
+    curves = curves / starts
+
+    avg_curve = curves.mean(axis=0)
+    pct_band = {
+        "p5": np.percentile(curves, 5, axis=0),
+        "p25": np.percentile(curves, 25, axis=0),
+        "p75": np.percentile(curves, 75, axis=0),
+        "p95": np.percentile(curves, 95, axis=0),
+    }
+
+    def _round_list(arr: np.ndarray, digits: int = 6) -> list[float]:
+        return [round(float(v), digits) for v in arr]
+
+    return {
+        "config": config,
+        "status": "OK",
+        "avg_curve": _round_list(avg_curve),
+        "pct_band": {k: _round_list(v) for k, v in pct_band.items()},
+        "runs_curves": curves,
+        "final_return_pct": _percentiles(final_returns * 100.0),
+        "sharpe": _percentiles(sharpes),
+        "max_drawdown": _percentiles(drawdowns * 100.0),
+        "prob_negative_return": round(float((final_returns < 0).mean()), 4),
+        "best_run_total_return": round(float(final_returns.max()) * 100.0, 4),
+        "worst_run_total_return": round(float(final_returns.min()) * 100.0, 4),
+    }

evaluation/public_benchmarks.py

@@ -0,0 +1,117 @@
+"""V5.4.4 - public benchmark baselines computed from the universe's own
+index/bond proxies (SPY, TLT), so the rank book's edge can be stated
+against well-known public benchmarks - not just against the naive
+strategy baselines in evaluation/benchmark_comparison.py.
+
+No external API and no new data dependencies: both functions accept the
+exact same (dates × tickers) close-price pivot that
+benchmark_comparison::momentum_baseline() already consumes - SPY/TLT are
+ordinary columns of `ml/datasets/full_dataset.csv`'s wide close table.
+
+- compute_sp500_baseline(): buy-and-hold SPY, close-to-close daily
+  returns over the pivot's own window.
+- compute_60_40_baseline(): the classic 60% SPY / 40% TLT portfolio,
+  DAILY rebalanced (weights reset to 60/40 every day, so the portfolio
+  return is just the fixed-weight blend of the two legs' daily returns -
+  no drift compounding of the weights themselves).
+
+Pure pandas/numpy, no I/O, no torch. Missing tickers degrade to a
+SKIPPED status (None metrics) instead of raising - the same
+"missing data never changes behavior, never crashes" convention the
+rest of this package follows. Output keys mirror the existing baselines'
+`{"strategy", "net_sharpe", "total_return_pct"}` shape, plus an
+additive `status` field ("OK" / "SKIPPED: <reason>") since - unlike the
+strategy baselines, which work on any universe - these two CAN be
+uncomputable (a universe without SPY, or without TLT for the 60-40).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+SP500_PROXY_TICKER = "SPY"
+BOND_PROXY_TICKER = "TLT"
+SP500_WEIGHT = 0.60
+BOND_WEIGHT = 0.40
+
+
+def _daily_close_returns(close_pivot: pd.DataFrame, ticker: str) -> pd.Series:
+    """Close-to-close daily returns for one ticker, non-finite/zero-close
+    rows degraded to NaN and dropped (a 0 close would otherwise produce
+    inf via division)."""
+    if ticker not in close_pivot.columns:
+        return pd.Series(dtype=float)
+    closes = pd.to_numeric(close_pivot[ticker], errors="coerce")
+    closes = closes.where(closes > 0.0)
+    # fill_method=None (never pad): a NaN close must produce NaN returns
+    # that drop out below, not silently extend the last real close across
+    # a gap (which would fabricate flat 0.0% return days).
+    returns = closes.pct_change(fill_method=None)
+    return returns.replace([np.inf, -np.inf], np.nan).dropna()
+
+
+def _sharpe(daily_returns: pd.Series) -> float:
+    """Annualized Sharpe of a daily-return series - the identical formula
+    every baseline in evaluation/benchmark_comparison.py uses
+    (mean / std(ddof=1) * sqrt(252), 0.0 when fewer than 2 observations),
+    so benchmark numbers produced by the two modules can never disagree
+    on what "Sharpe" means."""
+    arr = np.asarray(daily_returns, dtype=float)
+    if arr.size < 2:
+        return 0.0
+    std = float(np.std(arr, ddof=1))
+    if std <= 0.0:
+        return 0.0
+    return float(np.mean(arr) / std * np.sqrt(252.0))
+
+
+def _result(strategy: str, daily_returns: pd.Series) -> dict:
+    sharpe = _sharpe(daily_returns)
+    total_return = float(np.prod(1.0 + np.asarray(daily_returns, dtype=float)) - 1.0) if daily_returns.size else 0.0
+    return {
+        "strategy": strategy,
+        "net_sharpe": round(sharpe, 4),
+        "total_return_pct": round(total_return * 100.0, 2),
+        "status": "OK",
+    }
+
+
+def _skipped(strategy: str, reason: str) -> dict:
+    return {
+        "strategy": strategy,
+        "net_sharpe": None,
+        "total_return_pct": None,
+        "status": f"SKIPPED: {reason}",
+    }
+
+
+def compute_sp500_baseline(close_pivot: pd.DataFrame) -> dict:
+    """Buy-and-hold SPY over close_pivot's own window: close-to-close
+    daily returns, annualized Sharpe + cumulative total return. Same
+    window, same Sharpe formula as the strategy baselines - the numbers
+    are directly comparable by construction."""
+    returns = _daily_close_returns(close_pivot, SP500_PROXY_TICKER)
+    if returns.empty:
+        return _skipped("sp500", f"no usable {SP500_PROXY_TICKER} closes in close_pivot")
+    return _result("sp500", returns)
+
+
+def compute_60_40_baseline(close_pivot: pd.DataFrame) -> dict:
+    """60% SPY + 40% TLT, daily rebalanced: each day's portfolio return is
+    `0.6 * spy_ret + 0.4 * tlt_ret` (fixed-weight blend, weights reset
+    every day - the textbook daily-rebalanced 60-40). Requires BOTH
+    proxies present; either one missing skips the whole benchmark rather
+    than silently computing a different allocation."""
+    spy_returns = _daily_close_returns(close_pivot, SP500_PROXY_TICKER)
+    tlt_returns = _daily_close_returns(close_pivot, BOND_PROXY_TICKER)
+    if spy_returns.empty or tlt_returns.empty:
+        missing = SP500_PROXY_TICKER if spy_returns.empty else BOND_PROXY_TICKER
+        return _skipped("60_40", f"no usable {missing} closes in close_pivot")
+    aligned = pd.concat(
+        {"spy": spy_returns, "tlt": tlt_returns}, axis=1, join="inner"
+    ).dropna()
+    if aligned.empty:
+        return _skipped("60_40", f"no overlapping {SP500_PROXY_TICKER}/{BOND_PROXY_TICKER} return dates")
+    portfolio_returns = SP500_WEIGHT * aligned["spy"] + BOND_WEIGHT * aligned["tlt"]
+    return _result("60_40", portfolio_returns)