project_net_worth
Project net worth under multiple scenarios using Monte Carlo simulation with user-defined returns and volatility. Evaluate probability of reaching a target and plan life events.
Instructions
Thought experiment: forward-looking Monte Carlo projection of net worth under caller-supplied assumptions, multi-scenario. Runs monthly GBM under one or more (return, vol) pairs in parallel, adds a fixed monthly contribution, applies one-time life events, and returns P10 / P25 / P50 / P75 / P90 trajectories per scenario. horizon_months accepts any length from 1 (next month) to 720 (60 years) — same tool answers short-horizon outlooks and long-horizon FIRE planning. target_value is optional: when supplied, the response includes probability of reaching it and median months to reach; when omitted, just the distribution at the horizon. All monetary inputs/outputs are in the requested currency (default USD). YOU MUST set scenarios[].expected_annual_return and scenarios[].annual_volatility explicitly and disclose them verbatim to the user — firma does NOT bake in defaults. For reference, brief.risk_summary carries the user's realized 90d annualized_return_pct and annualized_vol_pct — those make a natural 'historical' scenario you can contrast with bear/bull overlays. All scenarios share the same seeded shock sequence so cross-scenario differences reflect (return, vol) — not random noise. For current portfolio state, use get_market_brief — that is the diagnostic tool; this is the thought-experiment tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| currency | No | Currency for every monetary input and output (USD/KRW/EUR/JPY/CNY/GBP/HKD/INR/TWD). Default USD. The projection is unit-agnostic; this value is metadata for the response. | USD |
| initial_value | Yes | Starting net worth in `currency`. | |
| monthly_contribution | Yes | Net monthly contribution in `currency` (income − expenses). Can be negative. | |
| target_value | No | Optional net-worth target in `currency`. When provided, the response includes probability_of_reaching_target + median_months_to_target per scenario. Omit for pure distribution output. | |
| horizon_months | Yes | Projection horizon in months. 1 = next month outlook; 60 = 5-year planning; 360 = 30-year FIRE. Same tool for short and long horizons. | |
| scenarios | Yes | One or more scenarios to run side-by-side. Each carries its own label, expected_annual_return, and annual_volatility. For single-scenario calls just pass an array of length 1. | |
| life_events | No | Optional one-time cash flows along the horizon. | |
| iterations | No | Monte Carlo iterations per scenario. Default 1000 (P-band ±1.5%, ~500ms per scenario). Raise toward 10000 for smoother fan-chart curves at the cost of latency; lower to 100 for a quick sanity check. | |
| seed | No | Optional integer seed for reproducible runs. | |
| include_paths | No | Include the percentile trajectories per scenario (needed for fan-chart visualization). Set false for a lighter response (finals + probability + reach-month only). | |
| path_resolution | No | Path sample frequency when include_paths=true. 'yearly' samples every 12 months (≈10× smaller payload, sufficient for trajectory curves); 'monthly' returns every month (needed only for month-precise visualization). All monetary values are rounded to the nearest currency unit in the response — full precision stays in the projection engine. | yearly |