Skip to content

"Vibe-Trading: Your Personal Trading Agent"

22.2 KB
Raw Blame
"""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