Skip to content

README.md

Latest commit

 

History

History
198 lines (147 loc) · 6.85 KB

README.md

File metadata and controls

198 lines (147 loc) · 6.85 KB
Raw

Smart-Finance-LSTM

A Flask-based personal finance web application that uses LSTM (Long Short-Term Memory) neural networks to predict future monthly expenses by category, detect spending anomalies, and provide personalised financial recommendations.

Features

  • Expense Prediction — Per-category next-month forecasts powered by trained LSTM models with trend analysis and seasonal adjustments.
  • Anomaly Detection — Identifies unusual spending patterns by comparing predictions against recent history using z-score analysis.
  • Financial Health Score — Composite score based on predicted spending vs. budget limits and prediction confidence.
  • Budget Management — Set custom monthly budget limits and volatility thresholds for each category.
  • Recommendations — Actionable suggestions generated from predictions, budget alerts, and anomaly signals.
  • Transaction Management — Add individual transactions, bulk-upload CSV files (with duplicate merging), and delete entries.
  • Multi-user Support — Each user's transactions and budget are stored in separate JSON files under userdata/.
  • Demo Mode — Instantly explore the app using pre-loaded sample expense data without creating an account.
  • Model Comparison — Training pipeline compares LSTM, GRU, SimpleRNN, and Random Forest models per category and saves the best performer.

Tech Stack

Layer Technology
Web framework Flask 3.x + Jinja2
Deep learning TensorFlow / Keras 2.13 (LSTM, GRU, SimpleRNN)
Machine learning scikit-learn (MinMaxScaler, RandomForestRegressor)
Data processing pandas, NumPy
Visualisation Matplotlib, Plotly, Seaborn
Session storage Flask-Session
Serialisation joblib (scalers), Keras .keras (models)

Expense Categories

The application tracks spending across 7 categories:

  • Bills & Utilities
  • Education
  • Entertainment
  • food & Dining
  • health & Medical
  • shopping
  • Travel & Transportation

Project Structure

Smart-Finance-LSTM/
├── app.py                      # Flask application & all route handlers
├── smartfinance.py             # Core ML logic: models, predictions, anomaly detection, scoring
├── train.py                    # Training pipeline entry point
├── project_utilities.py        # Config, file storage, CSV validator, training logger
├── requirements.txt            # Python dependencies
│
├── best_expense_lstm_model.keras  # Pre-trained global LSTM model
├── category_models/            # Per-category trained model files (*_lstm.keras)
├── category_scalers/           # Per-category MinMaxScaler files (*_scaler.pkl)
│
├── realistic_expense_data.csv  # Full training dataset
├── sample_expense_data.csv     # Demo / quick-start dataset
│
├── templates/                  # Jinja2 HTML templates
│   ├── landing.html
│   ├── login.html
│   ├── dashboard.html
│   ├── add_transaction.html
│   ├── view_transactions.html
│   ├── set_budget.html
│   ├── results.html
│   ├── training.html
│   ├── loading.html
│   └── developer.html
└── static/
    └── loss_chart.png          # Training loss chart (generated during training)

Installation

Prerequisites

  • Python 3.9 or later
  • pip

Steps

# 1. Clone the repository
git clone https://github.com/Rugvedrc/Smart-Finance-LSTM.git
cd Smart-Finance-LSTM

# 2. Create and activate a virtual environment (recommended)
python -m venv venv
source venv/bin/activate      # macOS / Linux
venv\Scripts\activate         # Windows

# 3. Install dependencies
pip install -r requirements.txt

Usage

1. Train the Models (optional — pre-trained models are included)

python train.py

This will:

  1. Load and validate realistic_expense_data.csv.
  2. Aggregate transactions into monthly per-category sequences.
  3. Train LSTM, GRU, SimpleRNN, and Random Forest models for each category.
  4. Save the best model per category to category_models/ and scalers to category_scalers/.

2. Run the Web Application

python app.py

Open your browser at http://127.0.0.1:5000.

3. Quick Start with Demo Mode

On the login page, toggle Demo Mode to load pre-built sample data and explore all features without any setup.

CSV Upload Format

To import your own transaction history, prepare a CSV file with the following columns:

Column Type Example
Date Date string (YYYY-MM-DD) 2024-03-15
Category One of the 7 categories food & Dining
Amount Numeric 850.00

Duplicate transactions (same Date + Category + Amount) are automatically skipped during import.

How Predictions Work

  1. Data Aggregation — Raw transactions are grouped into monthly spending totals per category.
  2. Sequence Creation — A sliding window of 3 consecutive months forms each input sequence.
  3. Scaling — Each category's values are normalised with its own MinMaxScaler.
  4. LSTM Inference — The trained model predicts spending for the next month.
  5. Trend Adjustment — A weighted exponential average and recent growth rate are applied on top of the model output.
  6. Seasonal Adjustment — Hard-coded seasonal multipliers are applied for categories like Entertainment, Travel, and Shopping.
  7. Confidence Score — Derived from the coefficient of variation of recent months; more consistent spending yields higher confidence.

Application Routes

Route Description
/ Landing page
/login Login / demo mode entry
/dashboard Spending summary by category
/add_transaction Add a single transaction
/upload_csv Bulk import transactions from CSV
/view_transactions List, filter, and delete transactions
/set_budget Set per-category budget limits
/predict Run prediction and view full analysis
/predict_loading Loading screen before prediction
/predict_process Internal prediction processing endpoint
/load_demo Load sample demo data
/developer Developer / model info page

Configuration

Key settings are defined in project_utilities.py and smartfinance.py under the CONFIG dictionary:

Key Default Description
model_dir category_models Directory for saved per-category models
scaler_dir category_scalers Directory for saved per-category scalers
prediction_confidence_threshold 0.7 Minimum confidence to trust a prediction
lstm_anomaly_multiplier 2.0 Standard-deviation multiplier for anomaly threshold
min_historical_months 3 Minimum months of data required for prediction

License

This project is licensed under the terms of the LICENSE file included in the repository.