"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Agent tool: portfolio risk x-ray (Portfolio Studio slice).
Wraps ``backtest.risk_xray.compute_risk_xray`` with data fetching through the
standard loader fallback chain (``src.market_data.fetch_market_data``), so the
agent can ask "how risky is this basket" without caring which source serves
the prices. The computation itself is pure and unit-tested directly; this
file only does argument handling, panel shaping, and the JSON envelope.
"""
from __future__ import annotations
import json
import logging
from datetime import datetime, timedelta, timezone
from typing import Any, Callable, Mapping
import pandas as pd
from backtest.metrics import calc_bars_per_year
from backtest.risk_xray import MIN_HISTORY_DAYS, PERIODS_PER_YEAR, compute_risk_xray
from src.agent.tools import BaseTool
from src.market_data import fetch_market_data
logger = logging.getLogger(__name__)
_DEFAULT_LOOKBACK_DAYS = 365
_MAX_SYMBOLS = 50
# Candidate record keys that may carry the bar's date/timestamp after
# ``DataFrame.reset_index().to_dict("records")`` — loaders name the index
# differently ("date", "datetime", "trade_date", ...).
_DATE_KEYS = ("date", "datetime", "trade_date", "time", "timestamp")
class PortfolioRiskXrayTool(BaseTool):
"""Compute concentration, volatility, drawdown, tail risk, and
co-movement for a weighted basket of symbols."""
name = "portfolio_risk_xray"
description = (
"Portfolio risk x-ray: given symbols (and optional weights), fetch "
"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 baskets are normalized to sum to 1; "
"baskets with short positions preserve their signed exposure scale."
)
parameters = {
"type": "object",
"properties": {
"symbols": {
"type": "array",
"items": {"type": "string"},
"description": "Symbols in the basket, e.g. [\"AAPL\", \"MSFT\", \"SPY\"].",
},
"weights": {
"type": "object",
"additionalProperties": {"type": "number"},
"description": "Optional symbol → weight map. Equal weights when omitted.",
},
"start_date": {
"type": "string",
"description": (
"YYYY-MM-DD. Defaults to one year before end_date; monthly "
"bars use enough calendar months to meet the minimum history."
),
},
"end_date": {
"type": "string",
"description": "YYYY-MM-DD. Defaults to today (UTC).",
},
"source": {
"type": "string",
"description": "Data source preference; 'auto' (default) walks the fallback chain.",
},
"interval": {
"type": "string",
"description": "Bar interval passed to the loaders; defaults to '1D'.",
},
},
"required": ["symbols"],
}
def __init__(self, data_fetcher: Callable[..., dict[str, Any]] | None = None) -> None:
# Injectable for tests; production uses the real fallback chain.
self._fetch = data_fetcher or fetch_market_data
def execute(self, **kwargs: Any) -> str:
try:
return self._run(**kwargs)
except Exception as exc: # noqa: BLE001 — tool must always return JSON
logger.warning("portfolio_risk_xray failed: %s", exc)
return json.dumps(
{"status": "error", "error": str(exc)}, ensure_ascii=False, allow_nan=False
)
# ------------------------------------------------------------------
def _run(self, **kwargs: Any) -> str:
symbols = kwargs.get("symbols")
if not isinstance(symbols, list) or not symbols or not all(
isinstance(s, str) and s.strip() for s in symbols
):
raise ValueError("symbols must be a non-empty list of strings")
symbols = [s.strip() for s in symbols]
if len(symbols) > _MAX_SYMBOLS:
raise ValueError(f"too many symbols ({len(symbols)}); cap is {_MAX_SYMBOLS}")
weights = self._parse_weights(kwargs.get("weights"), symbols)
source = str(kwargs.get("source") or "auto")
interval = str(kwargs.get("interval") or "1D").strip()
start_date, end_date = self._parse_dates(
kwargs.get("start_date"), kwargs.get("end_date"), interval
)
raw = self._fetch(
codes=symbols,
start_date=start_date,
end_date=end_date,
source=source,
interval=interval,
# Volatility, VaR/ES and drawdown need consecutive bars; the
# shared row cap would sample the series down on longer windows.
max_rows=0,
)
closes = self._closes_frame(raw, symbols)
unresolved = raw.get("_unresolved") if isinstance(raw, Mapping) else None
# Calendar bars have the same annual count across markets; preserve
# the existing daily convention for other intervals.
token = interval.strip()
periods_per_year = (
calc_bars_per_year(token)
if token == "1M" or token.lower() == "1w"
else PERIODS_PER_YEAR
)
report = compute_risk_xray(closes, weights, periods_per_year=periods_per_year)
envelope = {
"status": "ok",
"data": report,
"meta": {
"start_date": start_date,
"end_date": end_date,
"interval": interval,
"source": source,
"unresolved_symbols": list(unresolved or []),
},
}
return json.dumps(envelope, ensure_ascii=False, indent=2, allow_nan=False)
# ------------------------------------------------------------------
@staticmethod
def _parse_weights(raw: Any, symbols: list[str]) -> dict[str, float]:
if raw is None:
return {sym: 1.0 / len(symbols) for sym in symbols}
if not isinstance(raw, Mapping):
raise ValueError("weights must be an object mapping symbol → number")
unknown = [sym for sym in raw if sym not in symbols]
if unknown:
raise ValueError(f"weights name symbols not in the basket: {sorted(unknown)}")
missing = [sym for sym in symbols if sym not in raw]
if missing:
raise ValueError(f"weights missing basket symbols: {sorted(missing)}")
return {sym: raw[sym] for sym in symbols}
@staticmethod
def _parse_dates(
start_raw: Any, end_raw: Any, interval: str = "1D"
) -> tuple[str, str]:
end = (
datetime.strptime(end_raw, "%Y-%m-%d").date()
if isinstance(end_raw, str) and end_raw
else datetime.now(timezone.utc).date()
)
if isinstance(start_raw, str) and start_raw:
start = datetime.strptime(start_raw, "%Y-%m-%d").date()
elif interval == "1M":
# Keep the same minimum sample gate for every interval. Include an
# extra calendar month so a partial boundary month is not needed.
start = (pd.Timestamp(end) - pd.DateOffset(months=MIN_HISTORY_DAYS + 1)).date()
else:
start = end - timedelta(days=_DEFAULT_LOOKBACK_DAYS)
if start >= end:
raise ValueError(f"start_date {start} must be before end_date {end}")
return start.isoformat(), end.isoformat()
@staticmethod
def _closes_frame(raw: Mapping[str, Any], symbols: list[str]) -> pd.DataFrame:
"""Shape the fetch envelope into a date-indexed close-price panel."""
series: dict[str, pd.Series] = {}
for sym in symbols:
records = raw.get(sym)
if not records:
continue
times: list[Any] = []
prices: list[float] = []
for record in records:
if not isinstance(record, Mapping) or "close" not in record:
continue
when = next((record[k] for k in _DATE_KEYS if k in record), None)
try:
price = float(record["close"])
except (TypeError, ValueError):
continue
times.append(when)
prices.append(price)
if not prices:
continue
# Mixed typed/untyped timestamps can't be sorted together; when any
# bar lacks a date, trust loader order (chronological) instead.
if any(when is None for when in times):
series[sym] = pd.Series(prices, name=sym)
else:
series[sym] = pd.Series(prices, index=times, name=sym).sort_index()
if not series:
raise ValueError("no close prices returned for any requested symbol")
return pd.DataFrame(series)