Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(risk-xray): honor bars_per_year=None in cross-market annualization

cgycorey660516bb26fd
diff --git a/agent/backtest/engines/base.py b/agent/backtest/engines/base.py
index 2c36ecdd1..0b90d2b1c 100644
--- a/agent/backtest/engines/base.py
+++ b/agent/backtest/engines/base.py
@@ -672,7 +672,7 @@ class BaseEngine(ABC):
loader: Any,
signal_engine: Any,
run_dir: Path,
- bars_per_year: int = 252,
+ bars_per_year: int | None = 252,
) -> Dict[str, Any]:
"""Full backtest pipeline.
diff --git a/agent/backtest/engines/crypto.py b/agent/backtest/engines/crypto.py
index 34c36f99e..72c253297 100644
--- a/agent/backtest/engines/crypto.py
+++ b/agent/backtest/engines/crypto.py
@@ -99,7 +99,7 @@ class CryptoEngine(BaseEngine):
loader: Any,
signal_engine: Any,
run_dir: Path,
- bars_per_year: int = 252,
+ bars_per_year: int | None = 252,
) -> dict[str, Any]:
self._validate_strict_resolution(config)
self._run_interval = str(config.get("interval", "1D"))
diff --git a/agent/backtest/engines/options_portfolio.py b/agent/backtest/engines/options_portfolio.py
index 8404db6c9..c53ed5012 100644
--- a/agent/backtest/engines/options_portfolio.py
+++ b/agent/backtest/engines/options_portfolio.py
@@ -175,7 +175,7 @@ def run_options_backtest(
loader: Any,
engine: Any,
run_dir: Path,
- bars_per_year: int = 252,
+ bars_per_year: int | None = 252,
) -> Dict[str, Any]:
"""Options backtest entry point.
@@ -555,7 +555,7 @@ def _calc_options_metrics(
equity: pd.Series,
initial_cash: float,
trades: List[Dict[str, Any]],
- bars_per_year: int = 252,
+ bars_per_year: int | None = 252,
) -> Dict[str, Any]:
"""Calculate options backtest metrics.
@@ -573,6 +573,20 @@ def _calc_options_metrics(
equity_vals = pd.to_numeric(equity, errors="coerce").astype(float)
path_is_finite = bool(n and np.isfinite(equity_vals.to_numpy()).all())
+ # Cross-market convention (runner.py passes bars_per_year=None): derive
+ # the effective bars per year from the observed calendar span, mirroring
+ # calc_metrics. Without this, every None comparison below (<= 0 / > 0)
+ # raises TypeError instead of returning metrics.
+ if bars_per_year is None:
+ if n >= 2:
+ first, last = equity_vals.index[0], equity_vals.index[-1]
+ diff = last - first
+ calendar_days = diff.days if hasattr(diff, "days") else 0
+ years = calendar_days / 365.25 if calendar_days > 0 else 1.0
+ bars_per_year = int(n / years) if years > 0 else 252
+ else:
+ bars_per_year = 252
+
final_raw: float | None = None
final_value: float | None = None
if n:
diff --git a/agent/backtest/risk_xray.py b/agent/backtest/risk_xray.py
index 7526e3c43..9dc7c7c5d 100644
--- a/agent/backtest/risk_xray.py
+++ b/agent/backtest/risk_xray.py
@@ -87,7 +87,7 @@ def compute_risk_xray(
closes: pd.DataFrame,
weights: Mapping[str, float],
*,
- periods_per_year: int = PERIODS_PER_YEAR,
+ periods_per_year: int | None = PERIODS_PER_YEAR,
var_levels: Sequence[float] = VAR_LEVELS,
min_history: int = MIN_HISTORY_DAYS,
) -> dict[str, Any]:
@@ -97,7 +97,9 @@ def compute_risk_xray(
closes: Close-price panel, one column per symbol, sorted by date.
weights: Symbol → weight. Renormalized to 1.0 with a warning when the
sum differs; must be long-only and reference existing columns.
- periods_per_year: Annualization factor for the bar interval.
+ periods_per_year: Annualization factor for the bar interval; ``None``
+ falls back to span-derived calendar annualization (mirrors
+ ``calc_metrics``) — the runner's cross-market convention.
var_levels: Tail levels for historical VaR / expected shortfall.
min_history: Minimum valid bars a symbol must have to be included.
@@ -187,19 +189,45 @@ def _concentration(w: np.ndarray) -> dict[str, Any]:
}
-def _volatility(port: pd.Series, ppy: int) -> dict[str, Any]:
+def _volatility(port: pd.Series, ppy: int | None) -> dict[str, Any]:
vol = float(port.std(ddof=1)) if len(port) > 1 else None
downside = port[port < 0]
downside_dev = float(downside.std(ddof=1)) if len(downside) > 1 else None
+ annualize = _annualize_factor(ppy, port.index)
return {
"daily_vol": _finite(vol),
- "annualized_vol": _finite(vol * math.sqrt(ppy)) if vol is not None else None,
+ "annualized_vol": _finite(vol * annualize) if vol is not None else None,
"downside_deviation_annualized": (
- _finite(downside_dev * math.sqrt(ppy)) if downside_dev is not None else None
+ _finite(downside_dev * annualize) if downside_dev is not None else None
),
}
+def _annualize_factor(ppy: int | None, index: Any = None) -> float:
+ """Return the annualization factor ``sqrt(periods_per_year)``.
+
+ ``ppy is None`` means the caller deliberately declined to specify a
+ per-market bar count — the runner's cross-market convention
+ (``bars_per_year=None``). Follow the same span-derived convention as
+ ``calc_metrics`` / ``run_validation`` / options metrics: effective bars
+ per year = observed bars per elapsed calendar year, so the x-ray's
+ annualized volatility agrees with the Sharpe metrics in the same run
+ card (a fixed 365 would sit ~18% higher for a 252-trading-day daily
+ series). Degenerate/empty indexes fall back to the default 252.
+ """
+ if ppy is not None:
+ return math.sqrt(float(ppy))
+ try:
+ first, last = index[0], index[-1]
+ diff = last - first
+ calendar_days = diff.days if hasattr(diff, "days") else 0
+ years = calendar_days / 365.25 if calendar_days > 0 else 1.0
+ bpy = int(len(index) / years) if years > 0 else 252
+ except (IndexError, TypeError):
+ bpy = 252
+ return math.sqrt(float(bpy))
+
+
def _drawdown(port: pd.Series) -> dict[str, Any]:
if port.empty:
return {"max_drawdown": None, "max_drawdown_start": None, "max_drawdown_trough": None}
diff --git a/agent/backtest/validation.py b/agent/backtest/validation.py
index 34fcaa42a..b17ec9ffa 100644
--- a/agent/backtest/validation.py
+++ b/agent/backtest/validation.py
@@ -285,6 +285,27 @@ def walk_forward_analysis(
}
+def _effective_bars_per_year(equity_curve: pd.Series) -> int:
+ """Derive an effective bars-per-year from the equity span.
+
+ Used when the runner declines to specify per-market bar counts
+ (``bars_per_year=None``, the cross-market calendar-day convention):
+ the observed number of bars per elapsed calendar year, falling back to
+ the default 252 for degenerate spans (empty/single-bar curves).
+ """
+ n = len(equity_curve)
+ if n < 2:
+ return 252
+ try:
+ first, last = equity_curve.index[0], equity_curve.index[-1]
+ diff = last - first
+ calendar_days = diff.days if hasattr(diff, "days") else 0
+ years = calendar_days / 365.25 if calendar_days > 0 else 1.0
+ except (IndexError, TypeError):
+ return 252
+ return int(n / years) if years > 0 else 252
+
+
# ─── Runner integration ───
@@ -293,7 +314,7 @@ def run_validation(
equity_curve: pd.Series,
trades: List[TradeRecord],
initial_capital: float,
- bars_per_year: int = 252,
+ bars_per_year: int | None = 252,
) -> Dict[str, Any]:
"""Run configured validation checks.
@@ -315,6 +336,13 @@ def run_validation(
v_cfg = config.get("validation", {})
results: Dict[str, Any] = {}
+ # Cross-market convention (runner.py passes bars_per_year=None): derive
+ # the effective bars per year from the observed calendar span, mirroring
+ # calc_metrics — otherwise _sharpe's np.sqrt(bars_per_year) raises
+ # TypeError for every validation-enabled cross-market run.
+ if bars_per_year is None:
+ bars_per_year = _effective_bars_per_year(equity_curve)
+
if "monte_carlo" in v_cfg:
mc_cfg = v_cfg["monte_carlo"] if isinstance(v_cfg["monte_carlo"], dict) else {}
results["monte_carlo"] = monte_carlo_test(
diff --git a/agent/tests/test_options_portfolio_correctness.py b/agent/tests/test_options_portfolio_correctness.py
index d766f5117..ca62c7566 100644
--- a/agent/tests/test_options_portfolio_correctness.py
+++ b/agent/tests/test_options_portfolio_correctness.py
@@ -132,3 +132,36 @@ def test_all_numeric_trade_pnl_emits_no_ignored_warning() -> None:
metrics = _calc_options_metrics(pd.Series([100.0, 150.0]), 100.0, trades)
assert not any("Ignored PnL" in w for w in metrics["warnings"])
json.dumps(metrics, allow_nan=False)
+
+
+def test_bars_per_year_none_does_not_crash() -> None:
+ # The runner passes bars_per_year=None for cross-market baskets
+ # (calendar-day convention). All three guards used to raise
+ # TypeError ('<=' / '>' not supported between NoneType and int).
+ # Zigzag path with multiple downside observations so the sortino guard
+ # is reached (a single negative return yields an undefined downside std,
+ # unrelated to the None bug under test).
+ equity = pd.Series(
+ [100.0, 90.0, 95.0, 85.0, 92.0, 80.0],
+ index=pd.date_range("2026-01-01", periods=6, freq="D"),
+ )
+ metrics = _calc_options_metrics(equity, 100.0, [], bars_per_year=None)
+
+ assert metrics["sharpe"] is not None
+ assert metrics["sortino"] is not None
+ assert metrics["annual_return"] is not None
+ assert not any(
+ "positive bars_per_year" in w or "bars_per_year" in w for w in metrics["warnings"]
+ )
+ json.dumps(metrics, allow_nan=False)
+
+
+def test_bars_per_year_none_on_degenerate_span_falls_back_to_default() -> None:
+ # A one-bar equity curve has no calendar span to derive from; it must
+ # fall back to the default factor instead of raising.
+ equity = pd.Series(
+ [99.0], index=pd.date_range("2026-01-01", periods=1, freq="D")
+ )
+ metrics = _calc_options_metrics(equity, 100.0, [], bars_per_year=None)
+ assert metrics["final_value"] == 99.0
+ json.dumps(metrics, allow_nan=False)
diff --git a/agent/tests/test_risk_xray.py b/agent/tests/test_risk_xray.py
index 415cdc814..3f7a2bab3 100644
--- a/agent/tests/test_risk_xray.py
+++ b/agent/tests/test_risk_xray.py
@@ -391,3 +391,101 @@ def test_run_backtest_emits_risk_xray_artifacts(tmp_path):
# signal lag and the terminal liquidation. The old target-frame report
# counted the latter as invested even though the position was closed.
assert metrics["risk_xray_avg_invested"] == pytest.approx(38 / 40, abs=1e-6)
+
+
+# ---------------------------------------------------------------------------
+# Cross-market annualization: bars_per_year=None (#1237)
+# ---------------------------------------------------------------------------
+
+
+def test_periods_per_year_none_uses_calendar_day_annualization():
+ # The runner passes bars_per_year=None for cross-market baskets (its
+ # comment: "calendar-day annualization"). math.sqrt(None) used to crash
+ # every multi-market backtest; the annualized fields must stay defined
+ # with the 365 calendar-day factor.
+ # Zigzag closes so both positive and negative return observations exist
+ # (a monotonic-up fixture has an empty downside series and cannot exercise
+ # the second math.sqrt call).
+ idx = pd.date_range("2026-01-01", periods=60, freq="D")
+ closes = pd.DataFrame(
+ {
+ "AAA": pd.Series([100.0 + (i % 5) * 2.0 - 4.0 for i in range(60)], index=idx),
+ "BBB": pd.Series([50.0 + (i % 7) * 1.0 - 3.0 for i in range(60)], index=idx),
+ }
+ )
+ result = compute_risk_xray(
+ closes, {"AAA": 0.5, "BBB": 0.5}, min_history=10, periods_per_year=None
+ )
+ vol = result["volatility"]
+ assert vol["annualized_vol"] is not None
+ assert vol["downside_deviation_annualized"] is not None
+ port = (closes.pct_change().dropna() * pd.Series({"AAA": 0.5, "BBB": 0.5})).sum(axis=1)
+ # Span-derived convention (mirrors calc_metrics): effective bars per year
+ # from the observed calendar span — NOT a fixed 365.
+ first, last = port.index[0], port.index[-1]
+ years = (last - first).days / 365.25
+ bpy = int(len(port) / years)
+ assert vol["annualized_vol"] == pytest.approx(port.std(ddof=1) * bpy**0.5)
+ assert vol["downside_deviation_annualized"] == pytest.approx(
+ port[port < 0].std(ddof=1) * bpy**0.5
+ )
+ _assert_strict_json(result)
+
+
+def test_periods_per_year_explicit_keeps_explicit_factor():
+ closes = _closes({"AAA": list(range(100, 160)), "BBB": list(range(50, 110))})
+ result = compute_risk_xray(
+ closes, {"AAA": 0.5, "BBB": 0.5}, min_history=10, periods_per_year=252
+ )
+ vol = result["volatility"]
+ assert vol["annualized_vol"] == pytest.approx(vol["daily_vol"] * 252**0.5)
+
+
+def test_run_backtest_with_bars_per_year_none_does_not_crash(tmp_path):
+ # The full crash contract: engine.run_backtest(..., bars_per_year=None),
+ # which base.py forwards into compute_risk_xray (issue trace
+ # runner.py:1260 -> composite.py:150 -> base.py:860).
+ from backtest.engines.base import BaseEngine
+
+ class _FlatEngine(BaseEngine):
+ def can_execute(self, symbol, direction, bar):
+ return True
+
+ def round_size(self, raw_size, price):
+ return float(raw_size)
+
+ def calc_commission(self, size, price, direction, is_open):
+ return 0.0
+
+ def apply_slippage(self, price, direction):
+ return price
+
+ dates = pd.bdate_range("2026-01-05", periods=40)
+ data_map = {
+ "AAA": pd.DataFrame(
+ {"open": [100.0 + i for i in range(40)], "close": [100.0 + i for i in range(40)]},
+ index=dates,
+ ),
+ "BTC": pd.DataFrame(
+ {"open": [50.0 + 0.2 * i for i in range(40)], "close": [50.0 + 0.2 * i for i in range(40)]},
+ index=dates,
+ ),
+ }
+
+ class _Loader:
+ def fetch(self, codes, start_date, end_date, fields=None, interval="1D"):
+ return data_map
+
+ class _Signals:
+ def generate(self, data):
+ return {code: pd.Series(1.0, index=frame.index) for code, frame in data.items()}
+
+ engine = _FlatEngine({"initial_cash": 100_000.0})
+ metrics = engine.run_backtest(
+ {"codes": ["AAA", "BTC"], "start_date": "2026-01-05", "end_date": "2026-03-01"},
+ _Loader(),
+ _Signals(),
+ tmp_path,
+ bars_per_year=None,
+ )
+ assert metrics["risk_xray_annualized_vol"] is not None
diff --git a/agent/tests/test_validation.py b/agent/tests/test_validation.py
index 30f1b87e0..8ce2feabc 100644
--- a/agent/tests/test_validation.py
+++ b/agent/tests/test_validation.py
@@ -422,3 +422,33 @@ def test_load_trades_prefers_fill_derived_holding_bars(tmp_path: Path) -> None:
trades = _load_trades(tmp_path)
assert trades[0].holding_bars == pytest.approx(1.5)
+
+
+class TestBarsPerYearNone:
+ """Cross-market convention (runner passes bars_per_year=None, #1237)."""
+
+ def test_run_validation_with_none_does_not_crash(self) -> None:
+ eq = _make_equity(100)
+ trades = _make_trades([100, -50, 200, -30, 150])
+ config = {
+ "validation": {
+ "monte_carlo": {"n_simulations": 20},
+ "bootstrap": {"n_bootstrap": 20},
+ "walk_forward": {"n_windows": 3},
+ }
+ }
+ result = run_validation(config, eq, trades, 1_000_000, bars_per_year=None)
+ assert "bootstrap" in result and "walk_forward" in result
+ # _sharpe's np.sqrt(bars_per_year) must have been fed an int, not None.
+ assert result["bootstrap"]["observed_sharpe"] is not None
+ assert result["walk_forward"]["sharpe_std"] is not None
+
+ def test_run_validation_with_none_degrades_empty_equity(self) -> None:
+ result = run_validation(
+ {"validation": {"bootstrap": {"n_bootstrap": 10}}},
+ _make_equity(1),
+ [],
+ 1_000_000,
+ bars_per_year=None,
+ )
+ assert "bootstrap" in result