Snapshots
Snapshot tools — build an immutable point-in-time facts record and diff two of them.
Thin, stateless wrappers over finplan_core.snapshot: JSON in, JSON out. The
server never persists anything — saving snapshots is the client-side plugin’s job. The canonical check-in narrative template and the tools that serve and fill it.
The template is the only check-in artifact coupled to the snapshot schema — it
names which ${derived.*} / ${provenance.*} paths exist. So it lives here,
versioned alongside the snapshot model, and is served over MCP rather than bundled
into the plugin: a plugin-bundled copy would silently drift as derived evolves.
The filler that consumes this template (finplan_core.snapshot.fill_template) is
schema-agnostic and lives separately. This module serves the template text
(get_checkin_template) and exposes the filler over MCP (fill_checkin_template).
The template text itself lives in the sibling checkin_template.md so it can be
edited as markdown rather than a Python string literal; it is read once at import
via importlib.resources (works from both the source tree and an installed wheel).
It is pinned to snapshot_format_version 1 — the dotted paths mirror that schema’s
derived / provenance blocks, so bump and revise the two together.
build_snapshot
Section titled “build_snapshot”Build an immutable, versioned snapshot from a planning-state document.
| Parameter | Type | Default | Description |
|---|---|---|---|
as_of | string | null | Logical check-in date these facts represent, ISO format (YYYY-MM-DD). Required to build a snapshot; ignored for dry_run. |
state_json | object | null | A finplan_state document to capture, passed inline. Provide exactly one of state_json, state_path, or state_ref. |
state_path | string | null | Path to a finplan_state JSON file to capture (e.g. from save-state), loaded in place of state_json. The file must be tagged with “kind”: “finplan_state”. Local (stdio) transport only — rejected off stdio (e.g. a hosted HTTP server), where it would read the server’s filesystem rather than yours; send state_json inline there. Provide exactly one of state_json, state_path, or state_ref. |
state_ref | string | null | An opaque handle to a finplan_state document already uploaded to the server (via POST /state) and held in its state store. Resolves the stored, already-validated document without re-sending it inline — the way to build on a hosted server without the document entering model context. A ref-fed build reports migrated: false. Provide exactly one of state_json, state_path, or state_ref. |
dry_run | bool | false | Validate and migrate the state without building a snapshot. Returns {success, valid, migrated, errors, warnings, schema_drift, migrated_state?} and skips the projection — a cheap ‘is this state usable?’ check. |
assumption_preset | string | "standard" | Named set of return/volatility assumptions to apply. |
stocks_return | float | null | Override stock expected return (e.g. 0.07 = 7%) |
stocks_volatility | float | null | Override stock volatility (e.g. 0.15 = 15%) |
bonds_return | float | null | Override bond expected return |
bonds_volatility | float | null | Override bond volatility |
cash_return | float | null | Override cash expected return |
cash_volatility | float | null | Override cash volatility |
inflation | float | null | Annual inflation rate (e.g. 0.025 = 2.5%) used to inflate real-terms goal targets to nominal before computing each goal’s projected progress. Defaults to the engine’s canonical rate (2.5%); pass 0 to disable inflation. Recorded in the snapshot’s assumptions stamp so the projection round-trips. |
Returns {success, snapshot_ref, urls, note, as_of, derived, provenance, migrated, schema_drift, warnings} on a build, the dry-run shape above, or an error envelope (with structured errors on a validation failure). The full snapshot (the large facts echo + derived) is written to the server’s file store and never inlined: derived is enough to write the check-in narrative, and the full snapshot is fetched from urls.data (or by snapshot_ref) to fill the check-in template or diff against a later one.
diff_snapshots
Section titled “diff_snapshots”Compute structured, signed deltas between two snapshots (old -> new).
| Parameter | Type | Default | Description |
|---|---|---|---|
old_snapshot_json | object | null | The earlier finplan_snapshot document, passed inline. Provide exactly one of old_snapshot_json or old_ref. |
new_snapshot_json | object | null | The later finplan_snapshot document, passed inline. Provide exactly one of new_snapshot_json or new_ref. |
old_ref | string | null | snapshot_ref of the earlier snapshot in the server’s file store (as returned by build_snapshot), resolved in place of old_snapshot_json so the full document need not re-enter model context. Provide exactly one of old_snapshot_json or old_ref. |
new_ref | string | null | snapshot_ref of the later snapshot in the server’s file store (as returned by build_snapshot), resolved in place of new_snapshot_json. Provide exactly one of new_snapshot_json or new_ref. |
Returns {success, diff} or an error envelope.
get_checkin_template
Section titled “get_checkin_template”Return the canonical check-in narrative template as plaintext markdown.
Parameters: None
Returns {success, template}.
fill_checkin_template
Section titled “fill_checkin_template”Fill a check-in template’s facts markers from a snapshot.
| Parameter | Type | Default | Description |
|---|---|---|---|
snapshot_json | object | required | A finplan_snapshot document to fill the template from |
template | string | null | Template markdown with ${dotted.path} markers. Defaults to the canonical check-in template (same text as get_checkin_template). |
Returns {success, filled, unresolved} or an error envelope. unresolved lists any non-narrative markers that had no matching snapshot value.