Metadata-Version: 2.4
Name: personal-finance-tracker-besim
Version: 0.1.5
Summary: A Streamlit-based personal finance tracker with CSV import, auto-categorization, budgets, and PDF reports.
License: MIT
Keywords: advisor,budget,finance,personal-finance,streamlit
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: fpdf2>=2.7.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: plotly>=5.17.0
Requires-Dist: streamlit>=1.30.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Personal Finance Tracker

A web application for tracking, analysing, and advising on personal income and expenses, built with Python and Streamlit as a university final project.

---

## Project Description

Personal Finance Tracker helps you understand where your money goes — and where it is heading. You can manually add transactions, bulk-import from a CSV bank export, auto-categorize spending, set monthly budgets with visual progress indicators, receive AI-style financial advice and forecasts, and download a formatted PDF report — all stored locally in a SQLite database with no external dependencies.

---

## Features

- **Dashboard** — 4 KPI cards (income, expenses, net balance, transaction count) with vs-last-month deltas; period-filtered pie chart for spending by category; Income vs Expenses grouped bar chart with Savings Rate % overlay; Day of Week spending heatmap highlighting the busiest spending day.
- **Budget Manager** — Set monthly limits per category; color-coded progress bars (green / amber / red); budget health summary showing how many categories are on track, approaching, or over limit; set to 0 to remove a budget.
- **Advisor** — Smart financial advisor that analyses the last 3 months of transactions to forecast next-month spending per category (trend-adjusted), surface 4 actionable insight cards (savings outlook, rising categories, top category, saving tip), show a Forecast vs Historical grouped bar chart, and project year-end savings.
- **Transactions** — Combined page with 3 tabs: view and filter all transactions, add manually with auto-suggested category, or bulk-import via CSV upload with preview.
- **Export Report** — Select any month/year with data, preview income/expenses/net, and download a formatted PDF report in one click.
- **Auto-categorization** — Keyword matching assigns categories (Groceries, Transport, Dining, etc.) automatically when importing CSVs.
- **Persistent storage** — All data saved locally in `finance_tracker.db` (SQLite, no server required).

---

## Installation

```bash
# 1. Clone or download the project
cd finance_tracker

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

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

---

## How to Run

```bash
# From inside the finance_tracker/ directory:
streamlit run app.py
```

The app opens automatically at `http://localhost:8501`.

To load sample data, go to **Transactions → CSV Upload** and select `sample_data/sample_transactions.csv`.

---

## How to Run Tests

```bash
# From inside the finance_tracker/ directory:
pytest tests/ -v
```

All tests use an in-memory SQLite database — no files are created or modified. The test suite covers all 5 modules with 83 tests total.

---

## Class Overview

| Class | Module | Key Attributes | Key Methods | Purpose |
|---|---|---|---|---|
| `Transaction` | `transaction.py` | `id`, `date`, `description`, `amount`, `type`, `category` | `to_dict()`, `from_dict()`, `from_csv_row()` | Data model for a single financial record |
| `DatabaseManager` | `database.py` | `db_path` | `init_db()`, `insert_transaction()`, `get_all_transactions()`, `get_transactions_by_month()`, `update_category()`, `delete_transaction()`, `get_monthly_summary()`, `set_budget()`, `delete_budget()`, `get_budgets()` | SQLite persistence layer for all data |
| `Categorizer` | `categorizer.py` | `_keywords` | `categorize()`, `add_keyword()`, `get_categories()` | Keyword-based auto-categorization engine |
| `ReportGenerator` | `report.py` | — | `generate_monthly_report()` | Builds and returns PDF reports as bytes |
| `FinancialAdvisor` | `advisor.py` | `_db`, `_df` | `generate_report()`, `_compute_forecasts()`, `_generate_insights()` | Forecast and insight engine |
| `CategoryForecast` | `advisor.py` | `category`, `predicted_amount`, `avg_last_3_months`, `trend_pct`, `months_of_data` | — | Dataclass: per-category spending prediction |
| `SpendingInsight` | `advisor.py` | `level`, `message`, `category` | — | Dataclass: one actionable insight |
| `AdvisorReport` | `advisor.py` | `forecasts`, `insights`, `predicted_total_expenses`, `predicted_savings`, `current_month_income`, `savings_by_year_end`, `top_spending_category`, `busiest_day_of_week` | — | Dataclass: full advisor output |

Helper functions in `utils.py`: `parse_csv()`, `format_currency()`, `get_month_range()`

---

## CSV Format

The CSV import requires a header row with the following columns:

| Column | Type | Format | Example |
|---|---|---|---|
| `date` | string | `YYYY-MM-DD` | `2026-05-10` |
| `description` | string | Free text | `REWE Supermarket` |
| `amount` | number | Positive decimal | `52.30` |
| `type` | string | `income` or `expense` | `expense` |
| `category` | string | _(optional)_ | `Groceries` |

If `category` is omitted, it is assigned automatically from the description.

See `sample_data/sample_transactions.csv` for a ready-to-use example with 48 transactions.

---

## Project Structure

```
finance_tracker/
├── app.py                        # Streamlit entry point (5 pages)
├── advisor.py                    # Smart financial advisor engine
├── database.py                   # SQLite persistence layer
├── transaction.py                # Transaction dataclass
├── categorizer.py                # Keyword-based categorizer
├── report.py                     # PDF report generator (fpdf2)
├── utils.py                      # CSV parser and helper functions
├── finance_tracker.db            # Created automatically on first run
├── tests/
│   ├── conftest.py               # sys.path setup for pytest
│   ├── test_transaction.py       # 16 unit tests for Transaction
│   ├── test_categorizer.py       # 14 unit tests for Categorizer
│   ├── test_database.py          # 24 unit tests for DatabaseManager
│   ├── test_advisor.py           # 18 unit tests for FinancialAdvisor
│   └── test_utils.py             # 11 unit tests for utils helpers
├── sample_data/
│   └── sample_transactions.csv   # 48 realistic sample transactions
├── pyproject.toml                # Packaging metadata (bonus)
├── requirements.txt
└── README.md
```

---

## Technologies Used

| Library | Purpose |
|---|---|
| **Python 3.10+** | Core language |
| **Streamlit** | Web UI framework |
| **Pandas** | DataFrame manipulation and CSV handling |
| **Plotly** | Interactive charts |
| **fpdf2** | PDF report generation |
| **SQLite3** | Built-in database (no server needed) |
| **pytest** | Unit testing (83 tests across 5 modules) |
