portfolio-performance

name	portfolio-performance
description	Analyze portfolio performance versus benchmarks. Triggers when the user asks about "portfolio performance", "how has my portfolio done", "compare my portfolio to S&P 500 or Ibovespa", "portfolio returns", "Sharpe ratio for my portfolio", "track my investments", "dollarized P&L", or "portfolio vs benchmark".

Portfolio Performance Analyzer

Workflow Checklist

Copy and track progress:

Portfolio Performance Analysis:
- [ ] Step 1: Collect portfolio positions
- [ ] Step 2: Fetch historical prices for holdings
- [ ] Step 3: Fetch benchmark prices
- [ ] Step 4: Calculate position-level returns and dollarized P&L
- [ ] Step 5: Build portfolio daily returns series
- [ ] Step 6: Compute portfolio-level metrics (return, volatility, Sharpe, max drawdown)
- [ ] Step 7: Compare to benchmarks (relative return, alpha, beta)
- [ ] Step 8: Present full report

Step 1: Collect Portfolio Positions

Ask the user (or use what they provided) for each holding:

Field	Required	Notes
Ticker	Yes	e.g. AAPL, PETR4
Shares	Yes	Number of shares
Avg Cost	Recommended	Price paid per share for P&L
Purchase Date	Recommended	Defines performance start; default 1 year ago
Currency	Auto-detected	BRL if Brazilian ticker, else USD

Default lookback: 1 year ending today when no dates are provided.

Step 2: Fetch Historical Prices for Holdings

For each ticker call financial_search:

Query: "[TICKER] daily prices from [start_date] to [end_date]"

Extract: a time-sorted series of { date, close } rows.

Normalize each series to an index starting at 1.0 on the first date:

index[t] = close[t] / close[start]

This makes return comparison consistent regardless of price level.

Brazil note: If any ticker is a Brazilian asset (e.g. PETR4, BOVA11), price results will include _usd fields and an fx object with usd_brl and ptax_date. Use the close_usd field for USD-converted returns.

Step 3: Fetch Benchmark Prices

Select the appropriate benchmark(s) for the portfolio:

Portfolio type	Benchmark	Ticker
US stocks	S&P 500	SPY
Brazil stocks	Ibovespa	BOVA11
Mixed	Both	SPY + BOVA11

Query: "SPY daily prices from [start_date] to [end_date]"

Normalize the benchmark to 1.0 on the same start date as the portfolio.

Step 4: Calculate Position-Level Returns and Dollarized P&L

For each holding compute the following. If avg_cost is unknown, use start_date close as the cost basis.

Metric	Formula
Total Return %	(end_price / avg_cost - 1) × 100
Dollar P&L	(end_price - avg_cost) × shares
Cost Basis	avg_cost × shares
Current Value	end_price × shares
Portfolio Weight	current_value / Σ current_value

Brazil P&L in USD: If any holding is BRL-denominated, also compute dollar values using the fx.usd_brl rate from the price response:

cost_basis_usd = cost_basis_brl / purchase_fx_rate   (use current PTAX if purchase rate unknown)
current_value_usd = current_value_brl / current_fx_rate
gain_loss_usd = current_value_usd - cost_basis_usd

Step 5: Build Portfolio Daily Returns Series

Compute weighted daily returns for the portfolio:

daily_return[t] = Σ (weight_i × daily_return_i[t])

where daily_return_i[t] = close_i[t] / close_i[t-1] - 1.

Use beginning-of-period weights (buy-and-hold; do not rebalance). For equal-weight portfolios use weight_i = 1 / N.

Cumulative portfolio return at any date:

cumulative[t] = Π (1 + daily_return[τ]) for τ from start to t

Step 6: Compute Portfolio-Level Metrics

Using the daily returns series from Step 5:

Total Return

total_return = cumulative[end] - 1

Annualized Return

n_years = trading_days / 252
annualized_return = (1 + total_return)^(1/n_years) - 1

Annualized Volatility

volatility = stdev(daily_returns) × √252

Sharpe Ratio (annualized)

Use current risk-free rate appropriate for the portfolio currency:

• USD portfolio: 5.0% (approx US T-bill / Fed Funds)
• BRL portfolio: 10.5% (approx Selic rate)

daily_rf = (1 + annual_rf)^(1/252) - 1
excess_returns = daily_returns - daily_rf
sharpe = mean(excess_returns) / stdev(excess_returns) × √252

Interpretation: >1.0 = good, >2.0 = excellent, <0 = return below risk-free rate.

Maximum Drawdown

peak[t] = max(cumulative[τ]) for τ ≤ t
drawdown[t] = (cumulative[t] - peak[t]) / peak[t]
max_drawdown = min(drawdown[t])

Calmar Ratio (optional)

calmar = annualized_return / |max_drawdown|

Step 7: Benchmark Comparison

Compute the same metrics (total return, volatility, Sharpe, max drawdown) for each benchmark using its daily returns series.

Then compute relative metrics:

Metric	Formula
Alpha (absolute)	portfolio_return - benchmark_return
Relative Sharpe	portfolio_sharpe - benchmark_sharpe
Beta	cov(portfolio_daily, benchmark_daily) / var(benchmark_daily)
Tracking Error	stdev(portfolio_daily - benchmark_daily) × √252
Information Ratio	(portfolio_return - benchmark_return) / tracking_error

Beta interpretation: β > 1 = more volatile than benchmark; β < 1 = less volatile; β ≈ 0 = uncorrelated.

Step 8: Present Full Report

Output Format

---

Portfolio Performance Report Period: [start_date] → [end_date] ([N] trading days)

---

Holdings Performance

Ticker	Shares	Avg Cost	Current Price	Weight	Return	vs Benchmark
AAPL	50	$150.00	$185.00	45%	+23.3%	+8.2%
MSFT	30	$240.00	$295.00	55%	+22.9%	+7.8%

Dollarized P&L

Ticker	Cost Basis	Current Value	Gain / Loss	Return %
AAPL	$7,500	$9,250	+$1,750	+23.3%
MSFT	$7,200	$8,850	+$1,650	+22.9%
Total	$14,700	$18,100	+$3,400	+23.1%

Brazil positions: show BRL and USD columns side-by-side using PTAX rate.

Portfolio vs Benchmark

Metric	Portfolio	SPY	Difference
Total Return	+23.1%	+15.1%	+8.0%
Annualized Return	+23.1%	+15.1%	+8.0%
Annualized Volatility	18.5%	15.0%	+3.5%
Sharpe Ratio	0.98	0.68	+0.30
Max Drawdown	-12.3%	-10.5%	-1.8%
Beta	1.15	1.00	—

Key Insights

• Best performer: [ticker] (+X.X%) — [brief reason if known from news/context]
• Worst performer: [ticker] (-X.X%) — [brief reason if known]
• Alpha vs benchmark: +X.X pp — portfolio [outperformed / underperformed]
• Risk-adjusted (Sharpe): [value] vs benchmark [value] — [better / worse] risk-adjusted return
• Max drawdown: [value] — portfolio [recovered / still below] peak

Caveats

• Returns are price returns (excludes dividends) unless adjusted-close prices were used.
• Sharpe ratio assumes a normal distribution of daily returns.
• Beta and correlations require sufficient history (≥ 60 trading days) to be meaningful.
• Brazil positions:
  • Current values use the latest PTAX rate.
  • Cost basis conversion uses the original purchase-date FX rate when available; when that rate is unavailable, the current PTAX rate is used as a fallback.
  • This fallback tends to overstate USD losses / understate USD gains when BRL has depreciated and overstate USD gains / understate USD losses when BRL has appreciated. For precise historical P&L, provide the purchase-date exchange rate.
• Past performance does not guarantee future results.