"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
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.pyindex 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.pyindex 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.pyindex 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 = Nonefinal_value: float | None = Noneif n:diff --git a/agent/backtest/risk_xray.py b/agent/backtest/risk_xray.pyindex 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 thesum 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 Nonedownside = 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.pyindex 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.pyindex 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.pyindex 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 Nonediff --git a/agent/tests/test_validation.py b/agent/tests/test_validation.pyindex 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