"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Tests for the portfolio risk x-ray core and its agent tool."""
from __future__ import annotations
import json
import math
import numpy as np
import pandas as pd
import pytest
from backtest.risk_xray import (
_drawdown,
average_invested_weights,
compute_risk_xray,
render_risk_xray_markdown,
write_risk_xray,
)
from src.tools.portfolio_risk_tool import PortfolioRiskXrayTool
def _closes(series_map: dict[str, list[float]], start: str = "2026-01-01") -> pd.DataFrame:
n = max(len(v) for v in series_map.values())
idx = pd.date_range(start, periods=n, freq="D")
return pd.DataFrame({k: pd.Series(v, index=idx[: len(v)]) for k, v in series_map.items()})
def _assert_strict_json(payload: dict) -> None:
json.dumps(payload, allow_nan=False)
# ---------------------------------------------------------------------------
# weights handling
# ---------------------------------------------------------------------------
def test_weights_are_renormalized_with_warning():
closes = _closes({"AAA": list(range(100, 160)), "BBB": list(range(50, 110))})
result = compute_risk_xray(closes, {"AAA": 2.0, "BBB": 2.0}, min_history=10)
assert result["inputs"]["weights"] == {"AAA": 0.5, "BBB": 0.5}
assert any("renormalized" in w for w in result["warnings"])
_assert_strict_json(result)
def test_negative_weight_is_part_of_the_book():
closes = _closes({"AAA": list(range(100, 160)), "BBB": list(range(50, 110))})
result = compute_risk_xray(closes, {"AAA": 1.5, "BBB": -0.5}, min_history=10)
assert result["exposure"]["short_count"] == 1
assert result["exposure"]["gross"] == pytest.approx(2.0)
def test_unknown_symbol_rejected():
closes = _closes({"AAA": list(range(100, 160))})
with pytest.raises(ValueError, match="no price data"):
compute_risk_xray(closes, {"AAA": 0.5, "MISSING": 0.5})
def test_empty_panel_rejected():
with pytest.raises(ValueError, match="empty"):
compute_risk_xray(pd.DataFrame(), {"AAA": 1.0})
# ---------------------------------------------------------------------------
# concentration
# ---------------------------------------------------------------------------
def test_concentration_math():
closes = _closes(
{
"AAA": list(range(100, 160)),
"BBB": list(range(50, 110)),
"CCC": list(range(200, 260)),
}
)
result = compute_risk_xray(closes, {"AAA": 0.5, "BBB": 0.25, "CCC": 0.25}, min_history=10)
conc = result["concentration"]
assert conc["hhi"] == pytest.approx(0.375)
assert conc["effective_n"] == pytest.approx(1 / 0.375)
assert conc["top1_weight"] == pytest.approx(0.5)
assert conc["top3_weight"] == pytest.approx(1.0)
_assert_strict_json(result)
# ---------------------------------------------------------------------------
# history filter and calendar alignment
# ---------------------------------------------------------------------------
def test_thin_symbol_skipped_and_weights_renormalized():
closes = _closes(
{
"AAA": list(range(100, 160)),
"BBB": list(range(50, 110)),
"THIN": [10.0] * 5,
}
)
result = compute_risk_xray(
closes, {"AAA": 0.34, "BBB": 0.33, "THIN": 0.33}, min_history=30
)
assert [s["symbol"] for s in result["skipped"]] == ["THIN"]
assert result["inputs"]["symbols"] == ["AAA", "BBB"]
assert result["inputs"]["weights"] == pytest.approx({"AAA": 0.34 / 0.67, "BBB": 0.33 / 0.67})
_assert_strict_json(result)
def test_all_thin_rejected():
closes = _closes({"AAA": [1.0, 2.0, 3.0]})
with pytest.raises(ValueError, match="valid bars"):
compute_risk_xray(closes, {"AAA": 1.0}, min_history=30)
# ---------------------------------------------------------------------------
# drawdown / tail risk
# ---------------------------------------------------------------------------
def test_max_drawdown_on_hand_built_curve():
closes = _closes({"AAA": [100.0, 120.0, 60.0, 90.0]})
result = compute_risk_xray(closes, {"AAA": 1.0}, min_history=2)
assert result["drawdown"]["max_drawdown"] == pytest.approx(-0.5)
_assert_strict_json(result)
def test_drawdown_uses_initial_wealth_before_first_return():
dates = pd.date_range("2026-01-02", periods=2, freq="D")
result = _drawdown(pd.Series([-0.2, 0.125], index=dates))
assert result["max_drawdown"] == pytest.approx(-0.2)
assert result["max_drawdown_start"] == str(dates[0])
def test_drawdown_remains_negative_after_wealth_crosses_zero():
dates = pd.date_range("2026-01-02", periods=3, freq="D")
result = _drawdown(pd.Series([-1.2, 1.5, 1.0], index=dates))
assert result["max_drawdown"] == pytest.approx(-2.0)
assert result["max_drawdown_trough"] == str(dates[-1])
def test_expected_shortfall_on_known_tail():
returns_closes = [100.0]
for ret in [0.01] * 19 + [-0.10]:
returns_closes.append(returns_closes[-1] * (1 + ret))
closes = _closes({"AAA": returns_closes})
result = compute_risk_xray(closes, {"AAA": 1.0}, min_history=2)
tail = result["tail_risk"]
assert tail["expected_shortfall_95"] == pytest.approx(0.10)
assert tail["var_95"] is not None
_assert_strict_json(result)
# ---------------------------------------------------------------------------
# correlation / beta / diversification
# ---------------------------------------------------------------------------
def test_equal_weight_beta_is_one_against_equal_weight_proxy():
rng = np.random.default_rng(7)
a = rng.normal(0.001, 0.01, 80)
b = rng.normal(0.0005, 0.02, 80)
closes = _closes(
{
"AAA": 100 * np.cumprod(1 + a),
"BBB": 80 * np.cumprod(1 + b),
}
)
result = compute_risk_xray(closes, {"AAA": 0.5, "BBB": 0.5}, min_history=10)
assert result["correlation"]["beta_to_equal_weight"] == pytest.approx(1.0)
_assert_strict_json(result)
def test_identical_series_have_unit_diversification_ratio():
base = 100 * np.cumprod(1 + np.random.default_rng(3).normal(0, 0.01, 80))
closes = _closes({"AAA": base, "BBB": base.copy()})
result = compute_risk_xray(closes, {"AAA": 0.5, "BBB": 0.5}, min_history=10)
assert result["diversification"]["diversification_ratio"] == pytest.approx(1.0)
assert result["correlation"]["avg_pairwise_abs"] == pytest.approx(1.0)
_assert_strict_json(result)
def test_single_asset_correlation_section_is_null():
closes = _closes({"AAA": list(range(100, 180))})
result = compute_risk_xray(closes, {"AAA": 1.0}, min_history=10)
corr = result["correlation"]
assert corr["avg_pairwise_abs"] is None
assert corr["beta_to_equal_weight"] is None
assert corr["note"]
_assert_strict_json(result)
def test_constant_prices_never_emit_nan():
closes = _closes({"AAA": [10.0] * 60, "BBB": [20.0] * 60})
result = compute_risk_xray(closes, {"AAA": 0.5, "BBB": 0.5}, min_history=10)
_assert_strict_json(result)
# ---------------------------------------------------------------------------
# agent tool
# ---------------------------------------------------------------------------
def _stub_fetcher(closes_map: dict[str, list[float]]):
def fetch(*, codes, start_date, end_date, source, interval, **kwargs):
out: dict[str, object] = {}
idx = pd.date_range("2026-01-01", periods=max(len(v) for v in closes_map.values()), freq="D")
for code in codes:
values = closes_map.get(code)
if values is None:
continue
out[code] = [
{"date": str(idx[i].date()), "close": price} for i, price in enumerate(values)
]
out["_unresolved"] = [c for c in codes if c not in out]
return out
return fetch
def test_compute_risk_xray_surviving_symbols_zero_weight():
closes = pd.DataFrame({
"AAA": [10.0 + i for i in range(10)],
"BBB": [5.0] + [None] * 9,
})
with pytest.raises(ValueError, match="surviving symbols have zero total weight"):
compute_risk_xray(closes, {"AAA": 0.0, "BBB": 1.0}, min_history=5)
def test_tool_happy_path_equal_weights():
tool = PortfolioRiskXrayTool(
data_fetcher=_stub_fetcher(
{"AAA": list(range(100, 160)), "BBB": list(range(50, 110))}
)
)
payload = json.loads(
tool.execute(symbols=["AAA", "BBB"], start_date="2026-01-01", end_date="2026-03-01")
)
assert payload["status"] == "ok"
assert payload["data"]["concentration"]["hhi"] == pytest.approx(0.5)
assert payload["data"]["concentration"]["effective_n"] == pytest.approx(2.0)
assert payload["meta"]["unresolved_symbols"] == []
def test_tool_reports_unresolved_symbols():
tool = PortfolioRiskXrayTool(data_fetcher=_stub_fetcher({"AAA": list(range(100, 160))}))
payload = json.loads(tool.execute(symbols=["AAA", "NOPE"]))
# NOPE has no data → weights reference it → error envelope, still strict JSON
assert payload["status"] == "error"
assert "NOPE" in payload["error"]
def test_tool_rejects_bad_arguments():
tool = PortfolioRiskXrayTool(data_fetcher=_stub_fetcher({}))
payload = json.loads(tool.execute(symbols=[]))
assert payload["status"] == "error"
payload = json.loads(tool.execute(symbols=["AAA"], weights={"AAA": 0.5, "ZZZ": 0.5}))
assert payload["status"] == "error"
payload = json.loads(
tool.execute(symbols=["AAA"], start_date="2026-03-01", end_date="2026-01-01")
)
assert payload["status"] == "error"
def test_tool_survives_records_without_dates():
def fetch(*, codes, start_date, end_date, source, interval, **kwargs):
return {
"AAA": [{"close": 100 + i} for i in range(40)], # no date fields at all
# partially dated → whole series falls back to loader order
"BBB": (
[{"date": "2026-02-01", "close": 50.0}]
+ [{"close": 50 + i} for i in range(1, 40)]
),
}
tool = PortfolioRiskXrayTool(data_fetcher=fetch)
payload = json.loads(tool.execute(symbols=["AAA", "BBB"]))
assert payload["status"] == "ok"
# ---------------------------------------------------------------------------
# average_invested_weights / artifact writers (run emission slice)
def test_average_invested_weights_basic():
idx = pd.date_range("2026-01-01", periods=4, freq="D")
target_pos = pd.DataFrame(
{"AAA": [0.5, 0.5, 0.25, 0.0], "BBB": [0.25, 0.25, 0.25, 0.0], "CCC": [0.0] * 4},
index=idx,
)
weights, avg_invested = average_invested_weights(target_pos)
assert weights == {"AAA": pytest.approx(0.3125), "BBB": pytest.approx(0.1875)}
assert avg_invested == pytest.approx(0.5)
def test_average_invested_weights_rejects_flat_strategy():
idx = pd.date_range("2026-01-01", periods=3, freq="D")
target_pos = pd.DataFrame({"AAA": [0.0, 0.0, 0.0]}, index=idx)
with pytest.raises(ValueError, match="no average exposure"):
average_invested_weights(target_pos)
with pytest.raises(ValueError, match="empty"):
average_invested_weights(pd.DataFrame())
def test_average_invested_weights_carries_short_leg():
# Keep the short leg in the average book instead of refusing the x-ray or
# silently shrinking the report to the long half.
idx = pd.date_range("2026-01-01", periods=4, freq="D")
target_pos = pd.DataFrame(
{"AAA": [0.5, 0.5, 0.5, 0.5], "BBB": [-0.25, -0.25, -0.25, -0.25]},
index=idx,
)
weights, avg_invested = average_invested_weights(target_pos)
assert weights == {"AAA": pytest.approx(0.5), "BBB": pytest.approx(-0.25)}
assert avg_invested == pytest.approx(0.25)
def test_write_risk_xray_strict_json_and_markdown(tmp_path):
closes = _closes({"AAA": list(range(100, 140)), "BBB": [50.0 + 0.1 * i for i in range(40)]})
report = compute_risk_xray(closes, {"AAA": 0.6, "BBB": 0.4})
out = tmp_path / "risk_xray.json"
safe = write_risk_xray(out, report)
on_disk = json.loads(out.read_text(encoding="utf-8"))
assert on_disk == safe
_assert_strict_json(on_disk)
assert on_disk["concentration"]["hhi"] == pytest.approx(0.52)
md = render_risk_xray_markdown(report)
assert "# Portfolio Risk X-Ray" in md
assert "AAA" in md and "BBB" in md
assert "annualized vol" in md
@pytest.mark.parametrize("bbb_signal", [1.0, -1.0])
def test_run_backtest_emits_risk_xray_artifacts(tmp_path, bbb_signal):
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,
),
"BBB": 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(bbb_signal if code == "BBB" else 1.0, index=frame.index) for code, frame in data.items()}
engine = _FlatEngine({"initial_cash": 100_000.0})
metrics = engine.run_backtest(
{"codes": ["AAA", "BBB"], "start_date": "2026-01-05", "end_date": "2026-03-01"},
_Loader(),
_Signals(),
tmp_path,
)
out_json = tmp_path / "artifacts" / "risk_xray.json"
out_md = tmp_path / "artifacts" / "risk_xray.md"
warnings = json.loads((tmp_path / "run_card.json").read_text())["warnings"]
assert not any("Risk x-ray unavailable" in w for w in warnings)
assert out_json.exists() and out_md.exists()
payload = json.loads(out_json.read_text(encoding="utf-8"))
_assert_strict_json(payload)
if bbb_signal < 0:
positions = pd.read_csv(tmp_path / "artifacts" / "positions.csv", index_col=0)
means = positions.mean()
assert payload["inputs"]["weights"] == pytest.approx(means.to_dict(), abs=1e-8)
assert payload["exposure"]["gross"] == pytest.approx(means.abs().sum())
assert payload["exposure"]["net"] == pytest.approx(means.sum())
assert payload["exposure"]["short_count"] == 1
returns = pd.DataFrame({code: frame["close"] for code, frame in data_map.items()}).pct_change().dropna()
expected_vol = (returns @ means).std(ddof=1) * math.sqrt(252)
assert metrics["risk_xray_annualized_vol"] == pytest.approx(expected_vol)
assert "short" in out_md.read_text()
return
# The opening target is even, but actual weights drift with each symbol's
# realized price path; the x-ray must reflect execution truth, not preserve
# the optimizer's idealized 50/50 weights.
assert payload["concentration"]["hhi"] == pytest.approx(0.5010936725)
assert set(payload["inputs"]["symbols"]) == {"AAA", "BBB"}
assert "# Portfolio Risk X-Ray" in out_md.read_text(encoding="utf-8")
assert metrics["risk_xray_hhi"] == pytest.approx(payload["concentration"]["hhi"])
assert metrics["risk_xray_effective_n"] == pytest.approx(payload["concentration"]["effective_n"])
assert metrics["risk_xray_annualized_vol"] is not None
# Execution truth has two flat observations: the initial next-bar-open
# 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.clip(upper=0.0) ** 2).mean() ** 0.5 * 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
def test_long_window_requests_full_history_without_sampling():
"""Over the shared 250-row cap the fetch would sample the series down and
break consecutive-return math; the tool must ask for every row (#1461)."""
import math
n = 300
prices = [100.0 + i * 0.1 for i in range(n)]
idx = pd.date_range("2026-01-01", periods=n, freq="D")
def capped_fetch(*, codes, start_date, end_date, source, interval, max_rows=250, **kwargs):
rows = [{"date": str(idx[i].date()), "close": price} for i, price in enumerate(prices)]
if max_rows and len(rows) > max_rows:
step = math.ceil(len(rows) / max_rows)
rows = rows[::step]
return {codes[0]: rows, "_unresolved": []}
tool = PortfolioRiskXrayTool(data_fetcher=capped_fetch)
payload = json.loads(tool.execute(symbols=["AAA"], interval="1D"))
assert payload["status"] == "ok"
assert payload["data"]["inputs"]["aligned_days"] == n
assert payload["data"]["inputs"]["return_observations"] == n - 1
_assert_strict_json(payload)
# ---------------------------------------------------------------------------
# Downside deviation: zero-target RMS over every return period
# ---------------------------------------------------------------------------
def _closes_from_returns(returns: list[float]) -> pd.DataFrame:
idx = pd.date_range("2026-01-01", periods=len(returns) + 1, freq="D")
path = [100.0]
for value in returns:
path.append(path[-1] * (1.0 + value))
series = pd.Series(path, index=idx)
return pd.DataFrame({"AAA": series, "BBB": series})
def test_downside_deviation_counts_equal_losses():
# Every losing bar loses exactly 1%: the sample std of the losses is zero,
# but the downside risk is not. Per 3-bar cycle: (0.01**2 + 0.01**2) / 3.
returns = [-0.01, -0.01, 0.03] * 13
result = compute_risk_xray(
_closes_from_returns(returns), {"AAA": 0.5, "BBB": 0.5}, min_history=10
)
expected = math.sqrt(0.0002 / 3) * math.sqrt(252)
assert result["volatility"]["downside_deviation_annualized"] == pytest.approx(expected)
_assert_strict_json(result)
def test_downside_deviation_defined_for_a_single_loss():
returns = [0.01] * 38 + [-0.02]
result = compute_risk_xray(
_closes_from_returns(returns), {"AAA": 0.5, "BBB": 0.5}, min_history=10
)
expected = math.sqrt(0.02**2 / 39) * math.sqrt(252)
assert result["volatility"]["downside_deviation_annualized"] == pytest.approx(expected)
def test_downside_deviation_is_zero_without_losses():
result = compute_risk_xray(
_closes_from_returns([0.01] * 39), {"AAA": 0.5, "BBB": 0.5}, min_history=10
)
assert result["volatility"]["downside_deviation_annualized"] == 0.0