SpendCrunch

A Python-based personal finance tracking tool that normalizes transactions from multiple sources, applies automatic categorization rules, and generates spending summaries.

Features

• Multi-source support: Import transactions from various banks and financial institutions (CSV, XLS, XLSX)
• Automatic categorization: Rule-based pattern matching with Hebrew and English support
• Row filtering: Filter transactions by status or other criteria (e.g., only process completed transactions)
• Multi-currency: Automatic conversion to primary currency (NIS)
• Excel output: One sheet per input file for easy review and manual categorization
• Skip category: Automatically excludes transfers, investments, and filtered transactions from spending analysis
• Summary generation: Monthly spending breakdowns by category with totals and averages

Installation

1. Clone the repository
2. Create a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Configuration

Create a configuration directory with the following files:

config/categories.yaml

Define your spending categories and subcategories:

categories:
  - name: Food
    subcategories:
      - name: Groceries
      - name: Restaurants
      - name: Coffee

config/rules.yaml

Define pattern-matching rules for automatic categorization:

rules:
  - pattern: "STARBUCKS|COFFEE|CAFE"
    category: Coffee
    case_sensitive: false
    priority: 10

config/currencies.yaml

Define exchange rates:

currencies:
  - code: NIS
    symbol: ₪
    default_exchange_rate: 1.0
  - code: USD
    symbol: $
    default_exchange_rate: 3.7

config/sources.yaml

Define data source configurations for each bank/institution:

sources:
  - name: bank_name
    type: csv
    encoding: utf-8
    skip_rows: 0
    date_column: "Date"
    description_column: "Description"
    amount_column: "Amount"
    currency: NIS
    row_filter:  # Optional: filter rows by column values
      Status: ["Done", "Completed"]  # Only process rows where Status is "Done" or "Completed"

Usage

Basic Workflow

1. Place data files in the data directory (CSV, XLS, or XLSX files)

2. Process and summarize (one command does it all):

python -m src.cli summarize --data-dir data --output-file output/summary.xlsx

This processes all files, applies categorization rules, and creates output/summary.xlsx with:

• Normalized Data: All transactions with categories
• Uncategorized: Transactions that need manual categorization
• Summary: Monthly spending by category
• Details: Category breakdown with transaction counts

3. Review output in Excel to verify categorization

Commands

# Process all data and generate summary
python -m src.cli summarize --data-dir <data_folder> --output-file <output_file>

# Process with custom config directory (e.g., sampleconfig)
python -m src.cli summarize --data-dir /Users/nadavsteindler/Desktop/spending/2025/data --config-dir sampleconfig --output-file /Users/nadavsteindler/Desktop/spending/2025/summary2025.xlsx

# Validate configuration files
python -m src.cli validate-config --config-dir config

# List uncategorized transaction patterns
python -m src.cli list-uncategorized --input-file output/summary.xlsx

Project Structure

spendcrunch/
├── src/
│   ├── cli.py              # Command-line interface
│   ├── models/             # Data models (Transaction, Config, etc.)
│   ├── utils/              # Configuration loader
│   ├── ingestion/          # File readers and parsers
│   ├── processing/         # Categorization engine
│   └── excel/              # Excel writer
├── tests/                  # Unit tests
├── config/                 # Configuration files (user-specific)
└── output/                 # Generated Excel files

Skip Category

The Skip category is for transactions that move money around but don't represent actual spending:

• Internal Transfers: Between your own accounts
• Investments: Buying/selling stocks, mutual funds
• Savings: Deposits to savings/pension accounts
• Filtered: Transactions excluded by row filters (e.g., cancelled/declined transactions)
• ATM: ATM withdrawals

Skip transactions are included in summaries like any other category, allowing you to filter them out in Excel if desired. The Filtered subcategory is useful for debugging what was excluded by row filters configured in sources.yaml.

Development

Run tests:

pytest tests/

Add new rules by editing config/rules.yaml and re-running normalization.