Mc Portfolio Simulator

---
name: mc-portfolio-simulator
description: Monte Carlo forward P&L simulator for a book. Simulates 10,000 correlated return trajectories from the shrunk covariance matrix over a caller-specified horizon (default 60 trading days) and reports the full cumulative-return distribution, max-drawdown distribution, path VaR, and P(loss > X%) at 5/10/20/30% thresholds. Companion to position-sizer. Requires Stocks Basic. Runs on the free tier.
---

# mc-portfolio-simulator

You hand over a book (weights per ticker) and a horizon. The skill
fits the covariance matrix on the historical window, simulates N
correlated return trajectories forward, and reports the distribution
of outcomes.

Companion to `position-sizer` and to `risk-report --mc`. Same math
underneath: shrunk correlation × per-name vols → covariance →
Cholesky-factored path simulation. The three tools differ in framing:

- `position-sizer` produces target weights under a target vol.
- `risk-report` includes MC as one lens alongside historical VaR,
  drawdown, stress days.
- `mc-portfolio-simulator` is the standalone MC lens: you already
  have weights, you want the P&L distribution.

## When to invoke

- "Given my proposed weights, what's the 5th percentile 60-day
  outcome?"
- Comparing two candidate books by tail severity
- Answering "how bad can this get" for a small book without needing
  full risk-report output
- The user says "monte carlo my book", "simulate this portfolio",
  "P(loss > 10%)", "forward P&L distribution"

Not for: predicting the direction (MC doesn't pick winners; it fans
the future out). Not for options portfolios (payoffs are non-linear;
this simulates linear returns).

## What you need

- A book: `--positions T=w,T=w,...`
- `MASSIVE_API_KEY` exported
- Stocks Basic plan minimum

Optional:

- `--simulation-days` (default 60): forward horizon in trading days.
- `--n-paths` (default 10000): Monte Carlo path count.
- `--tail {normal, student_t}` (default normal): innovation
  distribution. student_t gives fatter tails.
- `--tail-df` (default 4): student-t degrees of freedom.
- `--lookback-days` (default 252): historical window for covariance.
- `--vol {realized, ewma}` (default realized): per-name vol estimator.
- `--ewma-lambda` (default 0.94): EWMA decay when vol=ewma.
- `--shrinkage` (default 0.05): correlation shrinkage toward identity.
- `--seed` (default 42): rng seed for reproducibility.

## What you get back

Two output layers from one run.

**Layer 1: canonical JSON** matching [`output-schema.json`](./output-schema.json).
`cumulative_return_distribution` with mean, std, and p5/p10/p25/p50/p75/p90/p95.
`max_drawdown_distribution` with p5/p10/p25/p50/p75 (all negative).
`path_var_by_confidence` at 95/99. `loss_probabilities` at 5/10/20/30%
and `gain_probabilities` at 5/10/20%. Per-ticker annualized vols and
the exact weight vector used (may exclude tickers with insufficient
history).

**Layer 2: rendered note**. Composition table, cumulative-return
percentile block, path max-drawdown block, probability grid, one-line
Take. See [`references/rendering.md`](./references/rendering.md).

## How it works

1. **Pull daily aggs** for each ticker over `lookback_days * 1.6 + 14`
   calendar days.
2. **Align to common dates** across the book.
3. **Fit per-name vol** using `realized` or `ewma` on the aligned window.
4. **Correlation matrix + shrinkage** toward identity for numerical
   PD safety.
5. **Covariance matrix** from vols × correlation.
6. **Simulate paths** via `simulate_correlated_paths`:
   Cholesky-factored multivariate normal (or student-t via
   `sqrt(df/chi2(df))` scaling), one row per path per day. Mean of
   each daily-return distribution is the historical daily mean.
7. **Portfolio P&L per path** = sum over days of (weight vector ·
   per-name daily return). Path NAV = cumulative product of
   exp(daily returns).
8. **Distribution stats**: percentile summary on cumulative returns
   and path max-drawdowns. Path VaR at each confidence is
   `-quantile(cum_ret, 1-c)`. Expected shortfall averages the tail.
9. **Probability grid**: fraction of paths crossing each loss/gain
   threshold.

## Foundations used

- [`massive-api-patterns`](../massive-api-patterns) for REST auth,
  retry, and daily aggs.

## Output mode: note

Narrative note with a percentile grid. A single portfolio simulation
produces a handful of numbers per bucket; a note reads better than
a wide table.

## Endpoints used

- `GET /v2/aggs/ticker/{T}/range/1/day/{from}/{to}?adjusted=true` per
  ticker. One call per ticker per run.

## Doesn't handle (yet)

- **Options / non-linear payoffs.** Linear returns only.
- **Regime shifts.** Simulates from the fitted covariance; the
  regime is what the window captured.
- **Time-varying correlations.** Constant cov over the horizon.
  GARCH-DCC would improve this at the cost of much more machinery.
- **Path-dependent objectives.** Reports max drawdown per path but
  not path-dependent utility functions (constant proportional
  drawdown, etc.).
- **Explicit jump processes.** student_t fattens the marginals; a
  Merton-style jump-diffusion would add discrete crash events.

These are clean PR extensions. Output schema is forward-compatible.