Skip to content

Projections

Unified projection interface and return-assumption comparison.


Compare market-outcome percentiles under three return assumptions: conservative, moderate, and aggressive.

Parameter Type Default Description
initial_balance_cents int required Starting balance in cents
time_horizon_months int 360 Number of months to project (default 360, 30 years)
iterations int 1000 Number of Monte Carlo paths per assumption set
inflation float 0.025 Annual inflation rate as decimal (e.g., 0.03 = 3%; default 2.5%). When > 0, results are in today’s purchasing power (real dollars); 0 gives nominal dollars.

Returns percentile outcomes for the same balance run through each of three preset {mean, volatility} return assumptions, to help with risk/return tradeoffs. When inflation > 0, values are expressed in today’s purchasing power.


Run a financial projection with constant or time-varying returns.

Parameter Type Default Description
initial_balance_cents int required Starting balance in cents
expected_annual_return float null Expected annual return (e.g., 0.07 = 7%). Use with annual_volatility and time_horizon_months for constant-return projections.
annual_volatility float null Annual volatility/std dev (e.g., 0.15 = 15%). Use with expected_annual_return and time_horizon_months.
time_horizon_months int null Number of months to project. Required for constant-return mode. For timeline mode, the horizon is derived from the timeline length.
return_distribution_timeline list null List of monthly return distributions for time-varying returns (glide paths). Each entry: {‘month’: 1, ‘return’: 0.07, ‘volatility’: 0.15}. Month indices must be 1-indexed and sequential. Mutually exclusive with expected_annual_return/annual_volatility/time_horizon_months.
monthly_contribution_cents int 0 Constant monthly contribution in cents, applied to every month. Use negative values for withdrawals. In retirement mode this is the pre-retirement (accumulation) contribution. Mutually exclusive with contribution_timeline.
contribution_timeline list null Explicit per-month contributions for time-varying saving/spending, mirroring return_distribution_timeline. Each entry: {‘month’: 1, ‘contribution_cents’: 100000}. Positive = contribution, negative = withdrawal. Month indices must be 1-indexed, sequential, and cover exactly the projection horizon. Mutually exclusive with monthly_contribution_cents and retirement_month.
retirement_month int null 1-indexed month at which contributions flip to withdrawals (accumulation -> decumulation) in a single call. Months before it contribute monthly_contribution_cents; from it onward the monthly cashflow is retirement_income_cents - retirement_withdrawal_cents. Mutually exclusive with contribution_timeline.
retirement_withdrawal_cents int 0 Gross monthly withdrawal in cents from retirement_month onward (>= 0). Requires retirement_month.
retirement_income_cents int 0 Monthly income in cents (e.g. Social Security) that offsets the withdrawal from retirement_month onward (>= 0), so the net withdrawal is retirement_withdrawal_cents - retirement_income_cents. Requires retirement_month.
method string "closed_form" Projection method (closed_form is recommended)
iterations int 1000 Number of Monte Carlo iterations (only used for monte_carlo method; never used by the target_depletion_probability solve)
seed int null Random seed, pinning which Monte Carlo draw runs. Only takes effect when method=‘monte_carlo’; ignored by the other methods and by the target_depletion_probability solve. Omit it and every method is already reproducible: deterministic and growth-only closed_form are analytical, closed_form with contributions or withdrawals samples with a fixed internal seed, and monte_carlo falls back to a fixed default seed. Vary this to sample a different draw.
cumulative_volatility bool true For method=‘closed_form’ only (ignored otherwise). If True (default), volatility compounds cumulatively over time (scales with sqrt(T)), widening percentile spreads as the horizon grows. If False, uses average per-period volatility (legacy behavior, producing roughly constant percentile spreads). False also keeps a projection with contributions or withdrawals on the analytic form, which is less accurate in the tails than the default sampling.
fees list[FeeSpec] null Stackable list of fee specs, each a discriminated union member keyed on ‘type’. Factorable fees (flat_percent, flat_dollar) apply under any method. Path-dependent fees — balance-dependent (tiered_percent, or flat_percent with floor_cents/cap_cents) and transaction-dependent (per_trade, charged each contribution/withdrawal month) — use method=‘auto’ (selects the deterministic engine at zero volatility) or method=‘deterministic’. closed_form and monte_carlo reject them.
inflation float | list[float] 0.025 Annual inflation rate as decimal (e.g., 0.03 = 3%; default 2.5%). Scalar applied uniformly, or list of annualized rates (one per month of the projection). Adjusts nominal returns to real returns via the Fisher equation; 0 gives nominal dollars.
percentiles list null Percentiles to compute (default: [10, 25, 50, 75, 90]).
summary_only bool false When True, skip writing the per-month time-series data file and return only the inline summary (inputs, outputs incl. final_balance_percentiles, and scalar projection_result metadata). Use it when you only need the headline percentiles — e.g. a per-account breakdown table — to avoid one file artifact per call. The per-month net_deposits and percentile_timelines are then unavailable; leave it False (default) when you need the full timeline.
target_depletion_probability float null Also solve for the largest constant monthly withdrawal, in today’s dollars, whose modeled depletion probability over the horizon is at or below this share (e.g. 0.1 = runs out on at most 10% of paths), reported in outputs.safe_withdrawal. With retirement_month the solved amount is the retirement withdrawal from that month on; otherwise it replaces monthly_contribution_cents from month 1. Not combinable with contribution_timeline. The projection itself still runs on your own inputs. The solve always draws its own fixed sample of 8192 paths (reported as total_paths), whatever method, iterations or seed are set to. Omit to skip.

Returns file URLs + compact inline summary. Full time series data is written to a file and accessible via the returned URLs. The inline summary contains only scalar metadata (inputs, outputs, scenario_id, iterations). Pass summary_only=True to skip the data file and return just that inline summary when the per-month series isn’t needed. outputs.depletion (inline, and on projection_result) gives the probability of running out and the depletion month and year percentiles, or null when no paths were sampled. outputs.safe_withdrawal gives the solved withdrawal when target_depletion_probability is passed, else null.


Run many independent projections in one call (vectorized run_projection).

Parameter Type Default Description
projections list required List of independent projections to run in one call. Each entry is a run_projection parameter object — at minimum {‘initial_balance_cents’: N} plus either constant-return params (expected_annual_return, annual_volatility, time_horizon_months) or a return_distribution_timeline, and optionally monthly_contribution_cents, contribution_timeline, retirement_month, retirement_withdrawal_cents, retirement_income_cents, method, iterations, seed, cumulative_volatility, fees, inflation, percentiles, summary_only, target_depletion_probability. Entries run independently and in parallel.

Returns: count, succeeded, failed, and projections.


Project a whole household plan: decompose UserState accounts into per-account projections and aggregate them into one after-tax outcome.

Parameter Type Default Description
state_json object null A full UserState document as JSON (the object /finplan:read-state loads, or manage_state returns). Its accounts, income_streams, and expenses drive the whole-plan projection. Required unless state_ref is supplied; takes precedence when both are given.
state_ref string null A live ‘st_…’ state handle returned by another tool. Use instead of state_json to avoid re-sending the full document; state_json takes precedence when both are given.
time_horizon_months int 360 Number of months to project (default 360 = 30 years).
assumptions_preset string "standard" Capital-market assumptions preset applied to every account’s allocation: ‘standard’ (stocks 7%/15%), ‘conservative’ (5%/18%), or ‘optimistic’ (10%/15%).
inflation float 0.025 Annual inflation rate as a decimal (e.g., 0.03 = 3%; default 2.5%). When > 0, all values are in today’s purchasing power (real dollars); 0 gives nominal dollars.
marginal_ordinary_rate float 0.22 Household marginal ordinary income tax rate for after-tax values (default 0.22).
ltcg_rate float 0.15 Household long-term capital gains tax rate for after-tax values (default 0.15).
percentiles list null Percentiles to compute (default: [10, 25, 50, 75, 90]).
method string "closed_form" Projection method (closed_form is recommended).
iterations int 1000 Monte Carlo iterations (only used for method=‘monte_carlo’).
seed int null Random seed, pinning which Monte Carlo draw runs (only used for method=‘monte_carlo’). Omitting it is still reproducible — monte_carlo falls back to a fixed default seed.
invest_residual_surplus bool true Whether the household surplus left over after account contribution pins is invested across the remaining accounts by balance. Set False to model the leftover surplus as held outside the plan (only pins and employer match flow into the accounts).
compute_income_tax bool true Compute each year’s federal, state, local and payroll (FICA/self-employment) tax from the state’s person, income streams, 401(k) deferrals, mortgages and deductible expenses, and subtract it from the surplus before it is invested (default true). The computed tax REPLACES every hand-entered TAXES-category expense (except one marked deductible_as=property_tax); the notes name each one replaced. Set false to keep your own TAXES expenses and invest the pre-tax surplus (income − expenses).

Returns file URLs + a compact inline summary. The full per-account and household time series and ‘income_tax_by_year’ live in the data file; the summary carries the first year’s row as ‘outputs.first_year_income_tax’ (see the returned schema URL and jq examples). The summary inputs include base_state_ref: reuse it as state_ref while it remains live instead of inlining the full state again. Each inline per_account entry carries that account’s ‘depletion’ (no household figure).