Skip to content

Projections

Unified projection interface and return-assumption comparison.

compare_return_assumptions

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
years int 30 Number of years to project
num_simulations int 1000 Number of Monte Carlo simulations per assumption set
inflation float 0.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). When > 0, results are in today's purchasing power (real 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_projection

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)
seed int null Random seed for reproducibility. Only takes effect when method='monte_carlo'; ignored by the closed_form (default), auto, and deterministic methods, which are analytical and not iterative.
adjust_timefactor 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).
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.0 Annual inflation rate as decimal (e.g., 0.03 = 3%). Scalar applied uniformly, or list of annualized rates (one per month of the projection). Adjusts nominal returns to real returns via the Fisher equation.
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.

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.

run_projections

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, adjust_timefactor, fees, inflation, percentiles. Entries run independently and in parallel.

Returns: count, succeeded, failed, and projections.

project_plan

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.0 Annual inflation rate as a decimal (e.g., 0.03 = 3%). 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 (only used for method='monte_carlo').
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).

Returns file URLs + a compact inline summary. The full per-account and household time series live in the data file (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.