How amonish1004/ml-project---personal-financial-digital-twin-with-explainable-spending-forecasting works
This repository implements a personal financial digital twin: it turns Czech bank transactions into monthly account features, predicts next-month debit spending, and presents forecasts, explanations, counterfactuals, savings planning, and exports in a web dashboard. The main runtime path is browser → REST API → validated inference; simulation and explanations delegate to the same prediction gateway. The README documents workspace capabilities not fully visible in the excerpts; those are represented without inferring their internal wiring. Evidence for API delegation and feature derivation is available in excerpts; training and some UI details are not sampled.
Main entry points: server.py REST API · app.js Twin dashboard · models.py CatBoost forecast · inference.py Prediction gateway
Components 19
Data preparation
- Berka transactions
data/raw/berka - Raw table loader
src/data/loader.py - Monthly aggregation
src/data/preprocessor.py - Account-month panel
data/processed/account_monthly_panel.csv - Supervised features
src/features/builder.py - Spending dataset
data/processed/supervised_spending_dataset.csv
Forecasting model
- CatBoost forecast
src/models/models.py - Chronological evaluation
src/models/evaluator.py - Global explainability
src/models/explainability.py
Twin services
- State validation
src/app/schema.py - Prediction gateway
src/app/inference.py - What-if simulator
src/app/simulator.py - Local TreeSHAP
src/app/explainer.py - PDF and Excel export
src/app/export.py
Web experience
- Twin dashboard
src/app/static/app.js - REST API
src/app/api/server.py - Savings goal planner
src/app/static/app.js - Financial action planner
src/app/static/app.js
Other components
- Financial user
Connections 25
- Financial user → Twin dashboard: uses
README.md - Twin dashboard → REST API: requests
- Berka transactions → Raw table loader: loads
src/data/loader.py - Raw table loader → Monthly aggregation: provides tables
- Monthly aggregation → Account-month panel: aggregates
src/data/preprocessor.py - Account-month panel → Supervised features: builds features
src/features/builder.py - Supervised features → Spending dataset: produces
src/features/builder.py - Spending dataset → Chronological evaluation: partitions
README.md - Spending dataset → CatBoost forecast: trains
- CatBoost forecast → Chronological evaluation: evaluated by
- CatBoost forecast → Global explainability: explained by
- REST API → State validation: validates request
src/app/api/server.py - REST API → Prediction gateway: predicts via
src/app/api/server.py - REST API → What-if simulator: simulates via
src/app/api/server.py - REST API → Local TreeSHAP: explains via
src/app/api/server.py - REST API → PDF and Excel export: generates exports
src/app/api/server.py - Prediction gateway → State validation: derives features
src/app/inference.py - Prediction gateway → CatBoost forecast: runs prediction
- What-if simulator → Prediction gateway: predicts scenarios
src/app/simulator.py - What-if simulator → State validation: validates states
src/app/simulator.py - Local TreeSHAP → Prediction gateway: gets forecast
src/app/explainer.py - Local TreeSHAP → CatBoost forecast: explains prediction
- Twin dashboard → Savings goal planner: plans savings
README.md - Twin dashboard → Financial action planner: synthesizes guidance
README.md - Twin dashboard → PDF and Excel export: requests downloads
README.md