What BEE is
The Budget & Economy Engine turns the numbers you enter into a structured, repeatable analysis of your household budget and the wider economy. It is a calculator and explainer, not an advisor: it shows the maths, the assumptions, and a range of scenarios, and leaves every decision to you. Nothing you enter leaves your control - no accounts, cookies, or trackers, and the API never caches your inputs.
How it works
Your inputs flow through the selected mode into the household and/or macro engines. If you pick a country, live CPI/macro data fills any gaps (your typed values always win). A Monte-Carlo scenario sweep then stress-tests the result, and everything is assembled into a multi-section report with inline charts.
household - macro - country"] --> MODE{"Mode"} MODE -->|Household| HH["Household engine"] MODE -->|Macro| MAC["Macro engine"] MODE -->|Comprehensive| HH MODE -->|Comprehensive| MAC CPI["CPI / macro providers
StatCan - FRED/BLS - INEGI
World Bank fallback"] --> MAC HH --> MC["Monte-Carlo scenario sweep
Rust hot path, Python fallback"] MAC --> MC MC --> REP["Multi-section report + charts"] REP --> DISC["Disclaimer: analysis only, not advice"]
Choosing a mode
| Mode | Use it when |
|---|---|
| Comprehensive | You want the full picture - your budget read against the macro backdrop. Recommended default. |
| Household | You only care about your own income, spending, savings, and debt. |
| Macro | You only care about the economy - inflation, growth, unemployment - with no personal data. |
Every input, explained
| Field | What it means | Example |
|---|---|---|
| Country | Enables live CPI/macro data. Leave as none to use only your typed numbers. | Canada |
| Currency | 3-letter ISO code for the household figures. | CAD |
| Monthly income | Total take-home (after-tax) income per month. | 9000 |
| Liquid savings | Cash you could access quickly - the buffer behind your resilience score. | 20000 |
| Monthly debt service | Total minimum monthly payments across all debts. | 1200 |
| Budget lines | One row per category: name, monthly amount, fixed vs variable. The split drives the flexibility analysis. | Rent / 2500 / fixed |
| GDP growth | Annual real GDP growth as a fraction. | 0.02 = 2% |
| Inflation | Annual inflation as a fraction. Blank pulls live CPI for the country. | 0.03 = 3% |
| Unemployment trend | Unemployment level/direction as a fraction. | 0.005 |
| Real-value comparison | Translate a nominal amount between two years given inflation. | 1000 from 2010 to 2026 |
Country & live data
Live data only fills gaps - anything you type wins. Sources by country:
| Country | Primary source | Fallback |
|---|---|---|
| Canada (CA) | Statistics Canada (keyless) | World Bank |
| United States (US) | FRED / BLS (API key upgrades fidelity) | World Bank |
| Mexico (MX) | INEGI (token upgrades fidelity) | World Bank |
API keys are optional - they improve fidelity but are never required. The keyless World Bank series is always available as a universal default.
Reading the report
- Snapshot - your headline numbers at a glance.
- Cash-flow - income vs fixed and variable spending, and what is left.
- Resilience - how long liquid savings cover expenses; debt load.
- Macro context - inflation, growth, and unemployment for your country.
- Scenarios - a Monte-Carlo sweep showing a range of outcomes, not one guess.
- Real-value erosion - what inflation does to a fixed amount over time.
- What to watch - the levers most sensitive in your situation.
Reproducibility
Every analysis can be exported with Download re-runnable script: a self-contained script that reproduces the exact same report from the same inputs - a result is never a black box.