"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
fix(risk): preserve signed exposure in long-short backtest reports
Haozhe Wuece0b451a80e
diff --git a/agent/backtest/risk_xray.py b/agent/backtest/risk_xray.pyindex 6eee8d47b..a556709a2 100644--- a/agent/backtest/risk_xray.py+++ b/agent/backtest/risk_xray.py@@ -7,8 +7,9 @@ loader imports — so the same computation serves the agent tool, the API,and tests. Data fetching lives in the caller.Conventions:-- Long-only v1: negative weights are rejected up front rather than silently- mis-computing concentration (a short leg is a different feature).+- Long-only weights are normalized to sum 1. Long/short weights keep their+ original exposure and signed returns; only concentration is normalized by+ gross share.- Non-finite inputs are never trusted and non-finite outputs are neveremitted: every reported float passes through ``_finite`` so the resultsurvives ``json.dumps(..., allow_nan=False)``.@@ -48,7 +49,11 @@ def _finite(value: float | None) -> float | None:def _validate_weights(closes: pd.DataFrame, weights: Mapping[str, float]) -> tuple[dict[str, float], list[str]]:- """Normalize weights to sum 1; reject unknown symbols and bad values.+ """Validate weights and preserve the exposure semantics for each book type.++ Long-only weights retain the historical normalization to sum 1. A book with+ a short leg keeps its original scale for exposure and return calculations;+ concentration alone is normalized by gross share in ``_concentration``.Returns the cleaned weight map (restricted to available columns) and anywarnings worth surfacing to the caller.@@ -69,12 +74,14 @@ def _validate_weights(raise ValueError(f"weight for {sym!r} is not a number: {raw!r}") from excif not math.isfinite(value):raise ValueError(f"weight for {sym!r} is not finite: {raw!r}")- if value < 0:- raise ValueError(- f"weight for {sym!r} is negative ({value}); the risk x-ray is long-only for now"- )cleaned[sym] = value+ if any(value < 0 for value in cleaned.values()):+ gross = sum(abs(value) for value in cleaned.values())+ if abs(gross - 1.0) > 1e-6:+ warnings.append(f"weights preserved at gross exposure {gross:.6f}; concentration uses gross shares")+ return cleaned, warnings+total = sum(cleaned.values())if total <= 0:raise ValueError("weights must sum to a positive value")@@ -96,8 +103,9 @@ def compute_risk_xray(Args: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.+ weights: Symbol → weight. Long-only weights are normalized to sum 1 with+ a warning when needed. Long/short weights preserve their actual+ exposure; concentration is computed from gross shares instead.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.@@ -135,14 +143,19 @@ def compute_risk_xray(if not kept:raise ValueError(f"no symbol has at least {min_history} valid bars")if skipped:- # Renormalize over the survivors so the x-ray still describes a- # fully invested basket, and say so.kept_weights = {sym: weights[sym] for sym in kept}- total = sum(kept_weights.values())- if total <= 0:- raise ValueError("surviving symbols have zero total weight")- weights = {sym: value / total for sym, value in kept_weights.items()}- warnings.append("weights renormalized over symbols that survived the history filter")+ if any(value < 0 for value in weights.values()):+ # Filtering any leg of a long/short book, including its last short+ # leg, must not change the surviving positions' original scale.+ warnings.append("history filter preserved original long/short exposure")+ else:+ # Preserve the long-only behavior: renormalize over survivors so the+ # x-ray still describes a fully invested basket, and say so.+ total = sum(kept_weights.values())+ if total <= 0:+ raise ValueError("surviving symbols have zero total weight")+ weights = {sym: value / total for sym, value in kept_weights.items()}+ warnings.append("weights renormalized over symbols that survived the history filter")aligned = frame[kept].dropna(axis=0, how="any")if len(aligned) < 2:@@ -171,6 +184,7 @@ def compute_risk_xray("last_date": str(aligned.index[-1]),},"concentration": _concentration(w),+ "exposure": _exposure(w),"volatility": _volatility(port_returns, periods_per_year),"drawdown": _drawdown(port_returns),"tail_risk": _tail_risk(port_returns, var_levels),@@ -183,13 +197,31 @@ def compute_risk_xray(def _concentration(w: np.ndarray) -> dict[str, Any]:- hhi = float(np.sum(w**2))- order = np.argsort(w)[::-1]+ # Concentration is a share-of-book measure, so normalize by gross exposure+ # here and nowhere else. The original signed weights still drive returns.+ gross = np.abs(w)+ total = float(gross.sum())+ if total > 0:+ gross = gross / total+ hhi = float(np.sum(gross**2))+ order = np.argsort(gross)[::-1]return {"hhi": _finite(hhi),"effective_n": _finite(1.0 / hhi) if hhi > 0 else None,- "top1_weight": _finite(float(w[order[0]])) if len(order) else None,- "top3_weight": _finite(float(w[order[:3]].sum())) if len(order) else None,+ "top1_weight": _finite(float(gross[order[0]])) if len(order) else None,+ "top3_weight": _finite(float(gross[order[:3]].sum())) if len(order) else None,+ }+++def _exposure(w: np.ndarray) -> dict[str, Any]:+ """Report actual gross/net exposure and the long and short sides."""+ return {+ "gross": _finite(float(np.abs(w).sum())),+ "net": _finite(float(w.sum())),+ "long_weight": _finite(float(w[w > 0].sum())),+ "short_weight": _finite(float(w[w < 0].sum())),+ "long_count": int(np.count_nonzero(w > 0)),+ "short_count": int(np.count_nonzero(w < 0)),}@@ -272,7 +304,7 @@ def _diversification(port_vol = float(port.std(ddof=1)) if len(port) > 1 else 0.0if port_vol <= 0 or not math.isfinite(port_vol):return {"diversification_ratio": None, "note": "portfolio variance is zero"}- ratio = float(np.dot(w, asset_vols) / port_vol)+ ratio = float(np.dot(np.abs(w), asset_vols) / port_vol)return {"diversification_ratio": _finite(ratio)}@@ -318,27 +350,20 @@ def average_invested_weights(target_pos: pd.DataFrame) -> tuple[dict[str, float]"""Derive the run's average basket from the target position frame.Returns ``(weights, avg_invested)``: the mean target weight per symbol- restricted to symbols the strategy actually held on average, and the mean- row sum (how much of the book was invested at all). The final row alone- would be the wrong object here, since many strategies end flat.+ restricted to symbols with a non-zero average signed exposure, and the mean+ signed row sum retained by the existing ``risk_xray_avg_invested`` metric.+ The final row alone would be the wrong object here, since many strategies+ end flat.Raises:- ValueError: when the frame is empty, the strategy never held- anything on average, or any symbol's average exposure is net- short — ``compute_risk_xray`` is long-only, and silently- x-raying just the long half of a long-short book would present- a partial basket as the whole strategy.+ ValueError: when the frame is empty or every symbol has zero average+ signed exposure. Short legs remain negative in the returned weights+ instead of shrinking the report to the long half of the book."""if target_pos is None or target_pos.empty:raise ValueError("target position frame is empty")means = target_pos.mean(axis=0)- short_book = [str(sym) for sym, w in means.items() if float(w) < 0]- if short_book:- raise ValueError(- "long-only x-ray cannot describe net short average exposure "- f"in {', '.join(short_book)}"- )- weights = {str(sym): float(w) for sym, w in means.items() if float(w) > 0}+ weights = {str(sym): float(w) for sym, w in means.items() if float(w) != 0.0}avg_invested = float(target_pos.sum(axis=1).mean())if not weights:raise ValueError("strategy held no average exposure")@@ -359,6 +384,12 @@ def render_risk_xray_markdown(report: dict[str, Any]) -> str:f"- window: {inputs['first_date']} .. {inputs['last_date']} "f"({inputs['aligned_days']} aligned days)",]+ exposure = report.get("exposure")+ if exposure:+ lines.append(+ f"- exposure: gross {exposure['gross']:.2%}, net {exposure['net']:.2%} "+ f"(long {exposure['long_weight']:.2%} / short {exposure['short_weight']:.2%})"+ )if conc.get("hhi") is not None:lines.append(f"- concentration: hhi {conc['hhi']:.4f}, "diff --git a/agent/src/tools/portfolio_risk_tool.py b/agent/src/tools/portfolio_risk_tool.pyindex f18d7a523..014b1bd74 100644--- a/agent/src/tools/portfolio_risk_tool.py+++ b/agent/src/tools/portfolio_risk_tool.py@@ -42,8 +42,8 @@ class PortfolioRiskXrayTool(BaseTool):"recent closes through the data fallback chain and compute ""concentration (HHI/effective N), annualized volatility, max drawdown, ""historical VaR/expected shortfall, diversification ratio, and "- "correlation/beta. Long-only; weights are renormalized when they do "- "not sum to 1."+ "correlation/beta. Long-only baskets are normalized to sum to 1; "+ "baskets with short positions preserve their signed exposure scale.")parameters = {"type": "object",diff --git a/agent/tests/test_risk_xray.py b/agent/tests/test_risk_xray.pyindex a68e5edfc..cbe91a5c9 100644--- a/agent/tests/test_risk_xray.py+++ b/agent/tests/test_risk_xray.py@@ -42,10 +42,11 @@ def test_weights_are_renormalized_with_warning():_assert_strict_json(result)-def test_negative_weight_rejected():+def test_negative_weight_is_part_of_the_book():closes = _closes({"AAA": list(range(100, 160)), "BBB": list(range(50, 110))})- with pytest.raises(ValueError, match="long-only"):- compute_risk_xray(closes, {"AAA": 1.5, "BBB": -0.5})+ 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():@@ -300,16 +301,17 @@ def test_average_invested_weights_rejects_flat_strategy():average_invested_weights(pd.DataFrame())-def test_average_invested_weights_rejects_long_short_book():- # A net-short leg must refuse the x-ray outright, not silently shrink the- # basket to the long half and present it as the whole strategy.+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,)- with pytest.raises(ValueError, match="long-only .* BBB"):- average_invested_weights(target_pos)+ 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):@@ -377,14 +379,22 @@ def test_run_backtest_emits_risk_xray_artifacts(tmp_path, bbb_signal):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"]- if bbb_signal < 0:- assert any("Risk x-ray unavailable" in w and "BBB" in w for w in warnings)- assert not out_json.exists() and not out_md.exists()- returnassert 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.diff --git a/agent/tests/test_risk_xray_long_short.py b/agent/tests/test_risk_xray_long_short.pynew file mode 100644index 000000000..a19f29756--- /dev/null+++ b/agent/tests/test_risk_xray_long_short.py@@ -0,0 +1,172 @@+"""Long/short exposure and return semantics for the portfolio risk x-ray."""++from __future__ import annotations++import json+import math++import pandas as pd+import pytest++from backtest.risk_xray import (+ average_invested_weights,+ compute_risk_xray,+ render_risk_xray_markdown,+)+++def _closes() -> pd.DataFrame:+ index = pd.date_range("2026-01-01", periods=5, freq="D")+ return pd.DataFrame(+ {+ "AAA": [100.0, 110.0, 105.0, 115.0, 120.0],+ "BBB": [200.0, 190.0, 196.0, 182.0, 175.0],+ },+ index=index,+ )+++def _manual(closes: pd.DataFrame, weights: dict[str, float]):+ returns = closes.pct_change(fill_method=None).dropna(how="any")+ portfolio = returns["AAA"] * weights["AAA"] + returns["BBB"] * weights["BBB"]+ return returns, portfolio+++def test_long_short_preserves_exposure_scale_for_returns_and_report():+ closes = _closes()+ small = compute_risk_xray(closes, {"AAA": 0.75, "BBB": -0.25}, min_history=2)+ large = compute_risk_xray(closes, {"AAA": 1.5, "BBB": -0.5}, min_history=2)++ assert small["exposure"] == {+ "gross": pytest.approx(1.0),+ "net": pytest.approx(0.5),+ "long_weight": pytest.approx(0.75),+ "short_weight": pytest.approx(-0.25),+ "long_count": 1,+ "short_count": 1,+ }+ assert large["exposure"] == {+ "gross": pytest.approx(2.0),+ "net": pytest.approx(1.0),+ "long_weight": pytest.approx(1.5),+ "short_weight": pytest.approx(-0.5),+ "long_count": 1,+ "short_count": 1,+ }+ assert large["inputs"]["weights"] == {"AAA": 1.5, "BBB": -0.5}++ _, small_port = _manual(closes, {"AAA": 0.75, "BBB": -0.25})+ _, large_port = _manual(closes, {"AAA": 1.5, "BBB": -0.5})+ assert small["volatility"]["daily_vol"] == pytest.approx(+ float(small_port.std(ddof=1))+ )+ assert large["volatility"]["daily_vol"] == pytest.approx(+ float(large_port.std(ddof=1))+ )+ assert large["volatility"]["daily_vol"] == pytest.approx(+ 2 * small["volatility"]["daily_vol"]+ )+ json.dumps(large, allow_nan=False)+++def test_concentration_uses_gross_share_without_rescaling_the_book():+ result = compute_risk_xray(_closes(), {"AAA": 1.5, "BBB": -0.5}, min_history=2)++ assert result["concentration"] == {+ "hhi": pytest.approx(0.625),+ "effective_n": pytest.approx(1.6),+ "top1_weight": pytest.approx(0.75),+ "top3_weight": pytest.approx(1.0),+ }+ assert result["exposure"]["gross"] == pytest.approx(2.0)+++def test_diversification_uses_original_weight_scale():+ closes = _closes()+ weights = {"AAA": 1.5, "BBB": -0.5}+ result = compute_risk_xray(closes, weights, min_history=2)+ returns, portfolio = _manual(closes, weights)+ expected = (+ 1.5 * returns["AAA"].std(ddof=1) + 0.5 * returns["BBB"].std(ddof=1)+ ) / portfolio.std(ddof=1)++ assert result["diversification"]["diversification_ratio"] == pytest.approx(expected)+++def test_history_filter_does_not_rescale_surviving_long_short_exposure():+ closes = _closes()+ closes["THIN"] = [1.0, 2.0, None, None, None]+ result = compute_risk_xray(+ closes,+ {"AAA": 1.5, "BBB": -0.5, "THIN": 10.0},+ min_history=3,+ )++ assert result["skipped"] == [+ {"symbol": "THIN", "reason": "only 2 valid bars (min 3)"}+ ]+ assert result["inputs"]["weights"] == {"AAA": 1.5, "BBB": -0.5}+ assert result["exposure"]["gross"] == pytest.approx(2.0)+ assert result["exposure"]["net"] == pytest.approx(1.0)+++def test_history_filter_preserves_scale_when_short_leg_is_skipped():+ closes = _closes().drop(columns="BBB")+ closes["THIN_SHORT"] = [200.0, 190.0, None, None, None]+ result = compute_risk_xray(+ closes,+ {"AAA": 1.5, "THIN_SHORT": -0.5},+ min_history=3,+ )++ assert result["skipped"] == [+ {"symbol": "THIN_SHORT", "reason": "only 2 valid bars (min 3)"}+ ]+ assert result["inputs"]["weights"] == {"AAA": 1.5}+ assert result["exposure"]["gross"] == pytest.approx(1.5)+ assert result["exposure"]["net"] == pytest.approx(1.5)+ assert result["warnings"] == [+ "weights preserved at gross exposure 2.000000; concentration uses gross shares",+ "history filter preserved original long/short exposure",+ ]+++def test_average_invested_weights_preserves_long_short_exposure():+ index = pd.date_range("2026-01-01", periods=4, freq="D")+ target_pos = pd.DataFrame({"AAA": [1.5] * 4, "BBB": [-0.5] * 4}, index=index)++ weights, avg_invested = average_invested_weights(target_pos)++ assert weights == {"AAA": pytest.approx(1.5), "BBB": pytest.approx(-0.5)}+ assert avg_invested == pytest.approx(1.0)+++def test_long_only_normalization_and_exposure_remain_compatible():+ closes = _closes()+ result = compute_risk_xray(closes, {"AAA": 2.0, "BBB": 1.0}, min_history=2)+ normalized = {"AAA": 2 / 3, "BBB": 1 / 3}+ _, portfolio = _manual(closes, normalized)++ assert result["inputs"]["weights"] == {+ "AAA": pytest.approx(2 / 3),+ "BBB": pytest.approx(1 / 3),+ }+ assert result["exposure"]["gross"] == pytest.approx(1.0)+ assert result["exposure"]["net"] == pytest.approx(1.0)+ assert result["exposure"]["short_count"] == 0+ assert result["volatility"]["daily_vol"] == pytest.approx(+ float(portfolio.std(ddof=1))+ )+ assert result["warnings"] == ["weights summed to 3.000000; renormalized to 1.0"]+++def test_markdown_reports_long_short_exposure():+ report = compute_risk_xray(_closes(), {"AAA": 0.75, "BBB": -0.25}, min_history=2)++ markdown = render_risk_xray_markdown(report)++ assert "gross 100.00%" in markdown+ assert "net 50.00%" in markdown+ assert "long 75.00%" in markdown+ assert "short -25.00%" in markdown+ assert math.isfinite(report["exposure"]["gross"])