Skip to content

"Vibe-Trading: Your Personal Trading Agent"

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.py
index 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 never
emitted: every reported float passes through ``_finite`` so the result
survives ``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 any
warnings 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 exc
if 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.0
if 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.py
index 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.py
index 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()
- return
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.
diff --git a/agent/tests/test_risk_xray_long_short.py b/agent/tests/test_risk_xray_long_short.py
new file mode 100644
index 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"])