Initial commit: Four-Quadrant Balance Sheet Matrix (FQBM) framework

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -0,0 +1,52 @@
+# Four-Quadrant Balance Sheet Matrix (FQBM)
+
+A unified institutional framework for monetary, fiscal, financial, and open-economy dynamics. This codebase implements the full FQBM from the white paper: simulation workbook (eight sheets), Monte Carlo stress engine, differential system model, and empirical regression suite.
+
+## Install
+
+```bash
+cd FOUR-QUADRANT_BALANCE_SHEET_MATRIX
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+```
+
+Optional: `pip install pytest` for tests.
+
+## Run
+
+- **Workbook (all sheets)**:  
+  `python -m fqbm.workbook.runner`  
+  Or from code: `from fqbm.workbook.runner import run_workbook` then `run_workbook(initial_state=..., mc_runs=100, export_path="out.xlsx")`.
+- **Monte Carlo**: `from fqbm.sheets.monte_carlo import run_n_simulations`
+- **Differential model**: `from fqbm.system.differential_model import solve_trajectory, check_stability`
+- **Regressions**: `from fqbm.empirical.regressions import run_inflation_pass_through, run_sovereign_spread, run_capital_flow_sensitivity`
+
+## Test
+
+```bash
+pytest tests/ -v
+```
+
+## Optional: Streamlit dashboard
+
+```bash
+pip install streamlit
+streamlit run scripts/streamlit_dashboard.py
+```
+
+## Optional: Historical scenarios (Part XI)
+
+Use preset scenarios in code: `run_workbook(scenario="asia_1997")` or `"gfc_2008"`, `"pandemic_2020"`, `"rate_shock_2022"`. See `fqbm.scenarios`.
+
+## References
+
+See [docs/REFERENCES.md](docs/REFERENCES.md) for Chicago Author–Date references (Adrian & Shin, BIS, Dornbusch, Fed H.4.1, IMF, McLeay et al., Obstfeld & Rogoff, etc.).
+
+## IPSAS compliance
+
+The framework includes an **IPSAS-aligned presentation layer** (IPSAS 1 statement of financial position, IPSAS 24 budget vs actual structure). Use `fqbm.ipsas.presentation.statement_of_financial_position(state, entity="central_bank"|"commercial_bank"|"consolidated")` and `budget_vs_actual_structure()`. Excel export adds IPSAS-style sheets when available. See [docs/IPSAS_COMPLIANCE.md](docs/IPSAS_COMPLIANCE.md) for the compliance assessment. **[docs/GAPS_AND_MISSING.md](docs/GAPS_AND_MISSING.md)** lists IPSAS standards and FQBM gaps. Additional helpers: **notes_to_financial_statements_structure**, **statement_of_financial_position_comparative**, **maturity_risk_disclosure_structure**, **cash_flow_from_state_changes**, **fx_translate**. Part VII: **repo_multiplier**, **margin_spiral_simulation**. Part VIII: **variation_margin_flow**, **ccp_clearing_simulation**.
+
+## Framework
+
+See [docs/framework_summary.md](docs/framework_summary.md) and the white paper for the theoretical foundation (Parts I–XVI).