Open-source personal and family financial planning powered by okama.
Quick start · Reports & charts · MCP · Client records · Languages
Three goals, one household: 1 Car (October 2029), 2 Home purchase (October 2031), 3 Early retirement (October 2040). Forecast in USD through 2070, on a logarithmic scale; blue median, shaded p25–p75 and p10–p90 ranges. Household inputs are fictional; returns use frozen historical observations. Zero and negative values are not shown on a log axis.
Build a monthly household plan, explore uncertainty, compare alternatives and export results under your own brand. Designed for financial planners, technically comfortable individuals and integration developers. Calculation quality comes first; Excel, charts and MCP provide ways to use the application while a future web interface is explored.
| Task | Available today |
|---|---|
| Model a household | Income, expenses, assets, fixed-payment loans, reserves and dated goals |
| Choose a portfolio approach | One pooled portfolio or explicitly allocated portfolios for each goal |
| Compare plans | Shared market scenarios, goal funding, unmet payments and portfolio/capital outcomes |
| Present results | Configurable Excel reports and interactive offline HTML charts |
| Share visuals | PNG and SVG charts, goal markers and independent logarithmic scales |
| Automate calculations | Python API and optional tools in the existing okama-mcp server |
| Keep client history | Local SQLite registry, versioned plans, scenarios and saved results |
Separate goal portfolios share synchronized market scenarios. Fixed-rate savings accounts are also supported, but are a different concept from investment portfolios for goals. See portfolio modes for allocation, transfers and funding rules.
Use Python 3.11+ and Poetry. From a local source checkout:
git clone https://github.com/mbk-dev/okama-planner.git
cd okama-planner
poetry env use python3.11
poetry install --extras reports
poetry run python examples/demo.py
poetry run python examples/portfolio_modes.pyThe first example compares a purchase now versus a deferred purchase. The second compares a
pooled portfolio with home and retirement portfolios on the same synthetic market scenarios.
Requests, results and an Excel comparison are saved under tmp/; neither example downloads
market data or needs a client database.
Prefer to browse first? Open the saved family inputs, results and Excel report examples. The three-goal hero input and result are included with dated assumptions and validation metadata. The USD example uses 5,000 Monte Carlo paths; its independent validation estimates plan success at 95.92% under the supplied assumptions. For exact numerical replay, use the versions in examples/versions.json; a seed alone does not freeze data or dependencies. Calculation contract →
import json
from pathlib import Path
from okama_planner import forecast
request = json.loads(Path("examples/readme-request.json").read_text())
result = forecast(request)The result is a JSON-compatible dictionary containing cash flows, goals, forecast metrics,
chart series and provenance. Complete input validation uses ForecastRequest; its JSON Schema
is available through ForecastRequest.model_json_schema().
Set your company name, contacts, logo and accent color. The exporter creates a new workbook; it does not require a private template or a pre-existing client file.
from okama_planner.reports import ReportBrand, export_report
export_report(
[{"label": "Family plan", "request": request, "result": result}],
"family-plan.xlsx",
brand=ReportBrand(company="Example Advisory", color="244C66"),
language="en", # en, ru, zh, de, es
)| Workbook sections | What they show |
|---|---|
| Summary, Budget, Balance | Plan outcomes, planned monthly cash flows, portfolio and net capital |
| Goals, Assumptions, Comparison | Goal funding, model inputs and differences between scenarios |
| Ledger | Detailed planned cash-flow requirements |
| Segments, Allocation, Segment balances | Portfolio assignments, strategies and account projections |
| Funding events, Transfers | Actual funded/unmet payments and transfers in joint portfolio modes |
| Branding, Instructions | Your presentation settings and guidance for reading the workbook |
The optional sheets reflect the result schema and portfolio mode. Excel presents saved forecast results: editing a cell does not rerun Monte Carlo. Change the input, recalculate and export again. Report details and fictional-brand examples →
from okama_planner.charts import export_charts
export_charts(result, "charts") # offline interactive HTML
export_charts(result, "charts/png", format="png")
export_charts(result, "charts/svg", format="svg")Portfolio and net capital are separate charts. HTML includes hover values, goal markers, logarithmic-scale controls and image download buttons. Direct PNG/SVG rendering requires Chrome or Chromium; HTML generation does not. This is a chart export, not a complete HTML financial-plan report or a hosted web application. Chart options →
The published okama-mcp 2.0.0 installs Planner 0.4.x with report dependencies
automatically. planner_forecast and planner_compare_modes call Planner's shared
calculation API while preserving the existing portfolio tools.
A configured local stdio installation adds six client-registry tools and
planner_export_report for Excel reports. HTTP exposes calculation tools and never
registers the local client/report tools. Standalone Planner chart exports and
retirement consumption-utility helpers are not exposed by these MCP tools.
Installation, local setup and worked MCP examples →
Designed for professional client work by financial advisors and financial planners. The local SQLite registry brings client identity, contacts, broker relationships and planning history together: one stable client record is linked to multiple versions of financial inputs, scenarios and saved calculations. It supports ongoing work with a client, from collecting information and choosing how to communicate to revisiting their financial plan.
Status: implemented in the Python API. okama_planner.storage provides client
creation, reading and updates, financial versions, scenarios and saved forecast results.
The shipped SQLite template contains schema and zero client records, plans or results.
Local registry access is available through the configured stdio tools in okama-mcp 2.0.0.
from pathlib import Path
from okama_planner.storage import PlannerStore
path = Path.home() / "planner-data" / "clients.sqlite3"
path.parent.mkdir(parents=True, exist_ok=True)
with PlannerStore.initialize(path) as store:
assert store.list_clients() == []initialize refuses to overwrite a file; PlannerStore.open(path) reopens an existing
database. Storage API, versioned snapshots and migrations →
Enter client identity directly through a human-only local browser form:
poetry run python -m okama_planner.client_form --database /path/to/clients.sqlite3Open the private URL printed by the command; stop with Ctrl+C. The Russian interface
creates and edits client records and saves financial input as append-only versions through
an advanced JSON editor. It uses only the local database and does not connect to an AI.
Use --initialize only to create a new empty database; existing files are never overwritten.
Add --legacy-database /path/to/lfp.sqlite3 to browse an existing LFP database read-only
and switch between the two interfaces. Planner edits stay in its separate database;
this option does not migrate data.
Form usage, validation and local access boundary →
The table below shows all 16 columns of Planner's client_registry, with three entirely
fictional records. Fields run down the table so the complete record remains readable.
These examples exist only in this README, not in a bundled database or a seed script.
They illustrate the registry supported by the storage API.
| Field | Alex Morgan | Priya Rao | Jordan Lee |
|---|---|---|---|
id — internal identifier |
1 | 2 | 3 |
code — stable client code |
c-0001 | c-0002 | c-0003 |
full_name — full name |
Alex Morgan | Priya Rao | Jordan Lee |
sex — recorded sex |
male | female | — |
birth_year — year of birth |
1985 | 1990 | 1978 |
email — email address |
alex@example.invalid | priya@example.invalid | jordan@example.invalid |
phone — telephone |
— | — | — |
telegram — Telegram handle |
— | — | — |
telegram_id — stable numeric Telegram ID |
— | — | — |
whatsapp — WhatsApp contact |
— | — | — |
max_messenger — MAX messenger contact |
— | — | — |
brokers — ordered broker list |
["Example Broker A"] | [] | — |
primary_channel — main communication channel |
|||
ips_sent_at — date the investment policy statement was sent |
2026-09-15 | — | 2026-10-01 |
note — advisor's working notes |
Annual plan review | First planning meeting | Retirement scenarios |
created_at — record creation timestamp (UTC) |
2026-09-01T09:00:00Z | 2026-09-08T10:00:00Z | 2026-09-20T08:30:00Z |
A dash means the value has not been recorded. For brokers, an empty list means the client
explicitly has no broker; a missing value means this is unknown. primary_channel points to
a contact that has been filled in. telegram_id preserves identity when a handle changes.
ips_sent_at records delivery of the investment policy statement, not automatic document creation.
The database separates the person from their changing financial information:
| Related table | All columns | Role in the advisor's workflow |
|---|---|---|
client |
id, registry_id, version, source_digest, note, created_at |
A version of the client's financial inputs; linked by registry_id, with a source fingerprint |
tax_residency |
id, registry_id, year, country, note |
Tax-residence country by calendar year, using an ISO two-letter country code |
Family members, assets, liabilities, budget items, goals, portfolios and scenarios belong to versions of client financial data in Planner. Saved calculation runs hold the input snapshot and model settings. This structure lets an advisor keep earlier inputs and compare later plans without treating an updated financial situation as a different person. Recording tax residency does not itself calculate jurisdiction-specific taxes.
Each advisor keeps their actual database outside the public repository. Configured local stdio tools in okama-mcp 2.0.0 access the registry through this storage API. Private advisory documents and internal skills are not part of the public package.
Available in this source checkout: Excel reports and chart interface text in English, Russian,
German, Spanish and Simplified Chinese (en, ru, de, es, zh). Select a language
with export_report(..., language="ru") or export_charts(..., language="ru").
The shared terminology table supplies translated captions.
See the offline five-language example,
user guides and coverage matrix and language contract.
Localized presentation includes currency-group reports, registry field/enum displays,
validation messages, chart controls and locale-specific dates and numbers. The companion
okama-mcp implementation supplies language selection for Planner and local client tools.
The additional locale formatting, registry presentation and validation helpers described
here are source changes after v0.4.1; the published v0.4.1 package contains the earlier
Excel/chart captions. The companion MCP additions likewise require its updated source.
SQL column names, JSON keys and API identifiers will remain stable across languages. Client names and other user-entered text are not automatically translated. Localized wording does not imply support for a country's tax or pension rules. Future web interfaces, additional languages and full HTML/PDF financial reports remain roadmap items.
The single-currency ForecastRequest does not perform FX conversion. The new
MulticurrencyRequest models joint asset/FX risk and explicit currency-conversion fees; see
the multi-currency contract. Jurisdiction-specific taxes and other
transaction fees must be reflected in supplied inputs.
Monte Carlo probabilities describe the supplied model and assumptions, not guaranteed outcomes.
Retirement consumption CE, gamma and equivalent-alpha helpers exist as a separate module; they are not yet integrated into forecasts, MCP or reports. Method and applicability →
Next steps include broader MCP exports and multilingual presentation. A web interface is a later direction. The standalone package contains no private client data, MBK documents, internal skills or dependency on the closed lfp application.
Multi-currency household plans are described in docs/multicurrency.md, with an offline RUB/USD/EUR example.
Tools for investing and financial planning.
| Project | What it helps you do |
|---|---|
| okama.io | Explore portfolios with interactive web tools. |
| okama | Analyze investments and portfolios in Python. |
| okama Data API | Access historical market and economic data. |
| okama-macro | Work with inflation and central-bank rate series. |
| okama-mcp | Use okama tools through an AI assistant. |
Ask questions, share examples and discuss financial planning.
AI-facing integrations use the restricted okama_planner.ai API. Names and contacts stay
inside Planner; MCP receives codes, and financial versions are read/written by Planner.
Personal identity intake uses a local human command, outside MCP. See
the privacy contract and local intake guide for protected surfaces,
signed anonymous exports and the filesystem isolation boundary. This contract change is
available in the updated source and has not yet been published to PyPI.