okama Planner 0.4.0 — charts, multilingual reports and client history

okama Planner 0.4.0 — charts, multilingual reports and client history

This release adds shareable forecast charts, localized financial-plan workbooks and a local database for advisors managing client plans.

Forecast charts

• Export portfolio and net-capital forecasts as HTML (default), PNG or SVG, using Apache ECharts and the saved Monte Carlo percentiles.
• Standalone HTML adapts to the browser window, includes a linear/logarithmic scale switch and supports PNG/SVG downloads.
• Numbered dashed goal markers and annotations show purchase and retirement dates. Export controls stay below the chart.
• Plot saved results without recalculating the forecast. Monetary values use the result currency; nonpositive values are handled explicitly in logarithmic mode.

Excel reports and currency examples

• English is the default report language; Russian, Simplified Chinese, German and Spanish are also supported through a shared terminology table.
• Annual Cash Flow presents calendar years horizontally, including separate goal-savings balances and annual contributions without counting internal deposits as household spending.
• Current amounts and chart labels follow the plan's base currency. Reports support linear and logarithmic portfolio/capital chart images and explain the supplied inflation indexation.
• Complete synthetic examples cover USD, EUR, CNY and RUB, with dated currency-specific inflation and reference-rate assumptions, separate purchase savings, assets, liabilities and retirement in 2040.
• Success calibration changes only initial invested capital by default, discloses the adjustment and validates on 5,000 independent trajectories with a predetermined seed. The attached foreign-currency workbooks show USD 95.92%, EUR 95.44% (German and Spanish) and CNY 99.92% under their supplied assumptions; these are illustrative model outcomes.

The foreign-currency examples currently share a SPY/AGG/GLD asset mix: 60/30/10 during accumulation and 30/60/10 during retirement. Returns are measured in each plan currency with unhedged currency exposure. These are synthetic examples, not client plans or separate locally tailored portfolios.

Local client storage

• Add a SQLite client registry with stable client codes, advisor contact fields and tax residency by calendar year.
• Save immutable financial-plan versions, full input snapshots, portfolio strategies, alternative scenarios and forecast runs.
• Preserve frozen return histories and link saved results to scenario inputs through a canonical request hash.
• Ship SQLAlchemy/Alembic migrations and an empty database template, with no client records. The forecast API remains usable without a database.

Additional updates and boundaries

• Include standalone retirement-consumption certainty-equivalent, Gamma and equivalent-alpha helpers. These are not connected to forecasts, MCP tools or reports; callers must supply actual funded real consumption paths and explicit preferences.
• Update documentation, synthetic illustrations and numerical replay checks across dependency patch versions.
• Preserve legacy forecasts and the pooled/goal-specific portfolio modes introduced in v0.3.0. Schema names and JSON keys remain language-independent.
• Expanded localization outside Excel and chart captions remains future work. The published MCP package/public HTTP server has not yet shipped these new client-storage and report capabilities.
• The planner does not infer jurisdiction-specific taxes or perform household FX conversion. Currency examples do not reproduce private custom bond-purchase or reserve policies.

Downloads

• okama_planner-0.4.0-py3-none-any.whl and okama_planner-0.4.0.tar.gz: Python package and source distribution.
• okama-planner-0.4.0-currency-examples.zip: four recalculated synthetic workbooks (English/USD, German/EUR, Spanish/EUR and Chinese/CNY), their input/result snapshots, assumptions and the terminology table.
• forecast.html: standalone responsive charts of the synthetic USD example.
• extraction-manifest.json and SHA256SUMS: tracked-source inventory and release-asset checksums.

Install the downloaded wheel with its optional report dependencies:

pip install 'okama_planner-0.4.0-py3-none-any.whl[reports]'

See chart exports, Excel reports and client storage.

Validation

• 586 tests passed; Ruff and all four CI example scripts passed.
• Wheel and source distributions built successfully and their contents were audited.
• Smoke-tested the unpacked wheel: offline forecast/chart export and SQLite client, plan, scenario and result round-trip. The shipped database template contains zero business records.
• All four attached workbooks were recalculated: zero formula errors; annual flows and separate goal balances/contributions match their saved ledgers.

Full changelog: v0.3.0…v0.4.0