Scenarios¶
Plan-scenario tools: create, apply, and compare scenarios against a base plan.
A scenario is a named, ordered list of typed overrides (a delta) applied
against a base UserState (design dev_docs/tasks/scenario-storage-design.md).
These tools are thin wrappers over finplan_core.scenarios: the numbers are
always re-derived server-side by running the whole-plan projection per scenario —
never narrated between tool calls.
The base is identified by a BaseRef: a mandatory state_hash (the content
hash manage_state returns) plus an optional state_ref accelerator (the
st_… handle from the ephemeral state store) so the full document need not be
re-sent through model context mid-session. An inline state_json always works
and takes precedence.
create_scenario¶
Create a plan scenario: a named, validated delta of typed overrides against a base plan.
| Parameter | Type | Default | Description |
|---|---|---|---|
base |
object | required | BaseRef the scenario is authored against: {'state_hash': ' |
name |
string | required | Human label, e.g. 'Retire at 60'. |
overrides |
list | required | Ordered, typed overrides (the delta), each tagged by 'kind': retirement_age, return_assumption, inflation, tax_rate, monthly_contribution, account_balance, income_change, expense_change, goal_target. Amounts are in cents. E.g. [{'kind': 'retirement_age', 'age': 60}]. |
description |
string | null | What question this scenario explores (e.g. 'does retiring at 60 still fund college?'). Defaults to a generated summary of the overrides. |
state_json |
object | null | The base UserState document inline. Optional when base.state_ref is still live; takes precedence when both are given. |
Returns: scenario, display_label, input_diff, and warnings.
apply_scenario¶
Resolve a scenario's state-shaped overrides against the base and return a state_ref to the resolved (hypothetical) UserState — plus the resolved state_json inline when return_state_json=True — for inspection or handing to other tools.
| Parameter | Type | Default | Description |
|---|---|---|---|
base |
object | required | BaseRef: {'state_hash': ' |
scenario |
object | required | The scenario to apply: a create_scenario document, or a minimal {'name': …, 'overrides': […]} sketch. |
state_json |
object | null | The base UserState document inline. Optional when base.state_ref is still live; takes precedence when both are given. |
return_state_json |
bool | false |
When True, also return the resolved hypothetical UserState inline as 'state_json'. Pass it to project_plan / run_projection (which take state_json, not state_ref) to drive the state-level drill-down off the scenario. |
Returns: scenario_id, display_label, state_ref, state_hash, warnings — plus the resolved state_json inline when return_state_json=True.
compare_scenarios¶
Compare plan scenarios against a base plan: one server-side operation that projects every scenario's whole plan and diffs the outcomes — never narrated arithmetic.
| Parameter | Type | Default | Description |
|---|---|---|---|
base |
object | null | BaseRef shared by the scenarios: {'state_hash': ' |
scenarios |
list | null | Scenarios to compare against the base: create_scenario documents or minimal {'name': …, 'overrides': […]} sketches. Mutually exclusive with scenario_set. |
scenario_set |
object | null | A portable finplan_scenario_set document ({'base': BaseRef, 'scenarios': […]}); its set-level base is authoritative. Mutually exclusive with scenarios. |
state_json |
object | null | The base UserState document inline. Optional when the base's state_ref is still live; takes precedence when both are given. |
time_horizon_months |
int | 360 |
Months to project (default 360 = 30 years). Shared by the base and every scenario so outcomes land on one comparable grid. |
assumptions_preset |
string | "standard" |
Capital-market assumptions preset the scenarios vary from: 'standard' (stocks 7%/15%), 'conservative' (5%/18%), or 'optimistic' (10%/15%). |
inflation |
float | 0.0 |
Baseline annual inflation rate as a decimal (e.g., 0.03 = 3%); an inflation override in a scenario replaces it for that scenario. When > 0, values are in today's purchasing power. |
percentiles |
list | null | Percentiles to compute (default: [10, 25, 50, 75, 90]). |
marginal_ordinary_rate |
float | 0.22 |
Household marginal ordinary income tax rate for after-tax values; a tax_rate override in a scenario replaces it for that scenario. |
ltcg_rate |
float | 0.15 |
Household long-term capital gains tax rate for after-tax values; a tax_rate override in a scenario replaces it for that scenario. |
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'). |
Returns file URLs + a compact inline summary; the per-month timelines live in the data file only (see the returned schema URL and jq examples).