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. 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.

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 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.