get_pretrade_risk_scan

Run a pre-trade risk scan for adding a single stock to the user's tracked portfolio, covering volatility/beta/VaR/drawdown deltas, market regime, a forward return distribution, position-sizing checks, sector/symbol exposure impact, and correlation against existing holdings.

Use this tool when:

• You need a risk-first check before evaluating or placing a trade.

• You want position-sizing guardrails (volatility, drawdown, beta, liquidity) evaluated against warn/fail thresholds, not just raw numbers.

• You need to see how adding this symbol would shift sector or per-symbol concentration in the existing portfolio.

• You want the new symbol's correlation to current holdings, to judge diversification benefit vs. redundant exposure.

Do NOT use this tool for:

• A standalone price-distribution simulation with no portfolio context → use get_monte_carlo instead.

• A general bullish/bearish read on the stock → use analyze_stock.

Parameters

symbol : str Exchange ticker in uppercase, e.g. "NVDA", "AAPL", "SPY".

Example

get_pretrade_risk_scan("NVDA")

Returns

dict with keys: symbol : str — normalized ticker asOf : str — ISO 8601 date the scan was computed regime : str — "bull" | "bear" | "chop" market regime regimeConfidence: float — 0–1 confidence in the regime classification riskDeltas : list — before/after risk metrics from adding the position, each item a dict with: label : str — e.g. "Annualized Volatility", "Beta (vs SPY)", "1-Day VaR (95%)", "Max Drawdown (1Y)" beforeValue : float — metric value for current portfolio afterValue : float — metric value after adding the position unit : str — "%" or "" (unitless, e.g. beta) higherIsRiskier : bool — whether an increase in this metric is worse distribution : dict — forward return distribution: {"bins": list, "frequencies": list, "kde_x": list, "kde_y": list} range_90 : dict — {"lower": float, "upper": float} 90 % CI on forward return (%) mean : float — expected forward return (%) threshold : float — reference return threshold used in the scan sizingChecks : list — pass/warn/fail guardrail checks, each a dict: label : str — "Volatility" | "Drawdown Risk" | "Market Exposure" | "Liquidity" status : str — "pass" | "warn" | "fail" detail : str — human-readable explanation with the thresholds used exposure : dict — portfolio concentration impact: available : bool — false if the user has no watchlist symbols to compare against bySector : list of {sector, currentPct, postTradePct, deltaPct} — empty list when available is false bySymbol : list of {symbol, currentPct, postTradePct, deltaPct} — empty list when available is false concentrationFlag : str — "pass" | "warn" | "fail" | "unknown" ("unknown" when available is false) assumedPositionWeight: float | None — None when available is false weightingMethod : str — e.g. "equal_weight_proxy" reason : str — present only when available is false; human-readable explanation (e.g. "No watchlist symbols to compare against. Add symbols to your watchlist to see portfolio exposure.") — surface this to the user instead of guessing why the section is empty correlation : dict — correlation of the new symbol to holdings: available : bool — false if the user has no watchlist symbols to compare against aggregate : dict | None — None when available is false; otherwise {avgCorrelationWithPortfolio, level, mostCorrelated: {symbol, correlation}, leastCorrelated: {symbol, correlation}} matrix : dict | None — None when available is false; otherwise {"symbols": list, "values": list[list[float]]} full pairwise correlation matrix reason : str — present only when available is false; human-readable explanation (e.g. "No watchlist symbols to compare against. Add symbols to your watchlist to see correlation.") — surface this to the user instead of guessing why the section is empty

Notes

• Requires a valid HPSILAB_API_KEY.

• Exposure and correlation sections assume the user has an existing tracked watchlist/portfolio. If none exists, "available" is false in both sections, their data fields are null/empty, and each includes a "reason" string explaining why — relay that reason to the user (e.g. suggest adding symbols to their watchlist) rather than treating the missing data as an error.