Portfolio Analytics

Purpose

Compute quantitative portfolio risk analytics before sizing and rebalance decisions.

Scope

• Holdings and weights.
• Historical price/return series.
• Optional benchmark.
• Optional sector map.
• Optional liquidity fields.

Non-goals

• No automatic rebalance.
• No absolute trade instructions.
• No live data fetching.

Input contract

Required inputs:

• HOLDINGS_CSV: rows with portfolio holdings and position weights or fields sufficient to compute weights.
• PRICE_CSV: historical prices or returns for held symbols.

Optional inputs:

• BENCHMARK_CSV: benchmark prices or returns for beta and relative-risk context.
• SECTOR_MAP_CSV: symbol-to-sector mapping for sector exposure.
• Liquidity fields: average daily value, average volume, free float, or similar liquidity context when available.

Execution workflow

1. Validate input files, required columns, date coverage, and symbol coverage.
2. Run scripts/analyze_portfolio.py with explicit holdings, price history, and optional benchmark or sector inputs.
3. Inspect metrics for risk level, concentration, correlation, benchmark sensitivity, and data limitations.
4. Prepare a handoff bundle for downstream sizing, rebalance, or risk-management review.

Required output format

1. Portfolio Metrics

   • Total portfolio value or normalized weight base, number of holdings, volatility, annualized return when supported, max drawdown, and risk-adjusted metrics when supported.

2. Benchmark Metrics

   • Benchmark volatility, benchmark drawdown, portfolio beta, tracking error, and relative return when benchmark data exists.

3. Correlation Summary

   • Average pairwise correlation, highest correlated pairs, and diversification observations.

4. Concentration Risk

   • Top positions, top-position weight, top-five weight, Herfindahl-Hirschman Index, and concentration warnings.

5. Sector Exposure

   • Sector weights and sector concentration when sector mapping exists.

6. Top Risk Contributors

   • Holdings with the largest estimated contribution to portfolio volatility or drawdown risk.

7. Confidence and Data Gaps

   • Confidence level, missing inputs, stale data, short history, incomplete holdings, missing sector data, missing liquidity data, or missing benchmark data.

8. Handoff Bundle

   • Include the exact marker fields listed in Handoff bundle.

Shared confidence rubric

• High: holdings are complete, weights reconcile, price history is long enough for the stated horizon, benchmark is available when beta or relative risk is discussed, and sector/liquidity coverage is broad.
• Medium: holdings and prices are usable, but one major input is partial, such as benchmark availability, sector mapping, liquidity coverage, or price-history length.
• Low: holdings are incomplete, weights do not reconcile, price history is short, benchmark is missing for beta-sensitive claims, or sector/liquidity coverage is sparse.

Guardrails

• Do not infer precise beta without benchmark data.
• Downgrade confidence for short price history or thin symbol coverage.
• Treat analytics as context for sizing, rebalance, and risk-management decisions, not as commands.

Handoff bundle

Include these exact marker fields:

• as_of_date
• holdings
• weights
• portfolio_metrics
• benchmark_metrics
• correlation_summary
• concentration_risk
• sector_exposure
• top_risk_contributors
• confidence
• data_gaps

Trigger examples

• "Analyze this portfolio's volatility, drawdown, and concentration before I resize positions."
• "Compute portfolio beta and sector exposure using these holdings and benchmark files."
• "Review my current holdings for correlation, top risk contributors, and data gaps."