Exposes okama 3.0's FinPlan — a plan modelled as an ordered sequence of portfolio stages, where each stage's terminal balance opens the next one per Monte Carlo scenario. That is what an accumulation phase followed by a withdrawal phase actually needs, and it is not expressible with the single-portfolio Monte Carlo tools.
New tools
finplan_forecast— Monte Carlo over the whole plan: percentile bands of the wealth path, terminal-wealth statistics, survival period, probability of success against a currency threshold, per-stage boundary balances and IRR.finplan_backtest— the same plan replayed on historical data, returning the wealth index and the cash-flow series in nominal (fv) or discounted (pv) terms.plot_finplan_forecast— percentile corridor with dashed stage boundaries and stage labels, so a multi-stage chart shows where the plan changes gear.
Notes
- Stages carry their own portfolio, horizon, cash-flow strategy and return distribution, so
FinPlanSpecis its own schema rather than a reuse ofMCSpec. - The chart is rebuilt through matplotlib's object-oriented API instead of calling
FinPlan.plot_forecast_monte_carlo(), which goes through global pyplot and is unsafe in FastMCP's worker threads. - No new dependencies — the
okama>=3.0.0floor is unchanged from v1.8.0.
Full Changelog: v1.8.0...v1.9.0