okama Planner 0.4.1 — multi-currency goals

okama Planner 0.4.1 — multi-currency goals and shared household funding

This release lets one financial plan fund goals in several currencies from a common household budget, with explicit conversion rules and joint asset/FX scenarios. Existing single-currency requests and saved plans remain supported.

Multi-currency plans

• Add MulticurrencyRequest: one household budget, native currency groups, dated contribution weights, an explicit funding order and conversion fees.
• Use either a shared portfolio or separate goal portfolios within each currency group.
• Supply opening exchange rates explicitly in base units per native unit. Asset and FX return histories share the same bootstrap month indices, preserving their supplied historical dependence.
• Keep native goal spending within its currency group. Cover common expenses and loan shortfalls using the specified household funding order.
• Calculate total portfolio/capital path by path before computing percentiles. Overall success requires all common and native obligations to be funded on the same scenario.
• Return schema 2.0 with native results, currency-labelled goals and per-path FX transfers. Store and replay complete requests and results through SQLite.

Reports and fixes

• Export responsive HTML (default), PNG and SVG for the overall base-currency forecast and each native group. Retain logarithmic scales, numbered goal markers and download controls.
• Add horizontal native Cash Flow sheets, currency-group strategies/current amounts, loan-financing inflows and FX traces to Excel. Native chart captions use the group's currency.
• Preserve user-entered goal labels and group IDs during localization. Reject mismatched native result currencies, input hashes and calendars before rendering.
• Complete expense-share pension segments after their last actual payment. Size their planned buffers using known future expenses and the current scenario quote, without looking ahead at future FX.

Example and downloads

The attached example is a fully fictional RUB/USD/EUR family. It mixes shared and goal-specific portfolios, property purchases, education goals and an expense-share pension. All asset returns, FX histories, rates and amounts are synthetic; the example demonstrates mechanics rather than a recommended portfolio.

• okama_planner-0.4.1-py3-none-any.whl and okama_planner-0.4.1.tar.gz: Python package and source distribution.
• okama-planner-0.4.1-multicurrency-example.zip: request/result snapshots, a recalculated Excel workbook and overall/native HTML/PNG/SVG forecasts.
• extraction-manifest.json and SHA256SUMS: source inventory and release-asset checksums.

pip install 'okama-planner[reports]==0.4.1'

See the multi-currency contract and reproducible example.

Validation

• 629 tests passed; Ruff and all five CI example scripts passed.
• Verified native currencies and unique chart sheets across all five Excel languages.
• Replayed the forecast after SQLite storage without a numerical difference.
• Recalculated the example workbook with zero formula errors.
• Built wheel/source distributions and smoke-tested the installed wheel with a multi-currency forecast, HTML/Excel export and SQLite round-trip.

Full changelog: v0.4.0…v0.4.1

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

okama Planner 0.3.0 — goal portfolios

Pooled and goal-specific investment portfolios now support complete household planning with explicit allocation, funding priorities, dated risk strategies and completion transfers.

• Compare both modes on one synchronized bootstrap of aligned asset history.
• Report actual funded and unmet amounts, full pension-stream funding, portfolio and household capital, allocation policies and segment balances.
• Reproduce the synthetic family example and export neutral Excel reports from saved requests.
• Preserve legacy FinPlan requests and saved results.

Validation: 355 tests, Ruff, independent financial/report review, and 311 recalculated workbook formulas without errors. Wheel, source archive and tracked-file manifest were audited. Retirement utility is excluded from this release.

The joint funding model uses monthly target-weight rebalancing. FX conversion, transaction fees and jurisdictional taxes are not modelled.

okama Planner v0.2.0 — neutral Excel reports

Neutral English Excel reports for saved household forecasts, under MIT.

• Optional reports extra with independently configurable company, contacts, accent color and local logo.
• Summary, monthly Budget, separate portfolio/net-capital Balance, Goals, both scenarios' Assumptions and Comparison, source Ledger and editing/licensing Instructions.
• Budget subtotals and scenario differences use Excel formulas. Forecast results stay fixed: change the request and rerun Planner to change financial assumptions.
• Two entirely synthetic branded workbooks are attached. Both were recalculated with LibreOffice: 298 formulas each, zero errors; their numerical values match across brands. Layout was visually checked.
• 225 tests and Ruff pass locally. The wheel with optional dependencies was installed in a clean environment without private lfp; both saved JSON results and a native forecast result exported successfully.

Configuration and boundaries: report guide.
The layout and fictional logos were created independently; no private templates or client records are used.
Gamma/equivalent alpha, goal-specific investment portfolios, country tax/FX models and a web UI remain unavailable. Financial calculation logic is unchanged.

The attached workbooks already contain cached formula values. Newly generated workbooks need Excel/LibreOffice recalculation before consumers read cached values. Wheel, sdist and both workbooks are covered by SHA256SUMS.

okama Planner v0.1.0

First public release of okama Planner, under the MIT license, with a clean repository history.

A standalone household financial-planning library powered by okama.FinPlan. The complete
request produces a monthly cash-flow ledger, loan and savings schedules, goal outcomes,
Monte Carlo metrics, portfolio and net-capital chart series, and numerical provenance.

The offline synthetic example compares a property purchase in July 2028 with July 2029 using
500 paths and seed 42. Full-plan success is 0.974 / 0.972; terminal portfolio medians are
25291.057126370935 / 25412.62632800031 USD. These are synthetic examples, not market forecasts.
Both complete results are attached and available in examples/.

Included: one investment portfolio with accumulation and retirement withdrawals; budgets,
fixed-payment loans, liquid reserves, non-working assets and dated goals. Goal-specific investment
portfolios, gamma/equivalent alpha, FX, jurisdictional taxes, white label reports and a web app
remain future work. The example script is a usage helper; no separate product CLI is required.

Use Python 3.11 and the installation/reproduction instructions in the README. The wheel and source
archive are attached with SHA256SUMS. A fresh source installation passed all 216 tests and Ruff;
both example calculations were exercised locally and in GitHub CI.

The optional local MCP integration is available in okama-mcp main.
Install this companion into the server environment. Existing indexed okama-mcp packages and the
public HTTP server have not been updated for this integration.