/finance_categorizer

Finance Categorizer

This command analyzes bank statement CSV files, corrects missing or incorrect categorizations, and generates comprehensive spending reports with visual indicators for high spending areas.

Instructions

• IMPORTANT: Use inline astral uv python code (with any libraries you need) to calculate the totals and percentages. Use `uv run python --with pandas --with <whatever library you need> -c "import pandas as pd; print(\"whatever you want here\")"` to test your code.
• Example: `uv run --with rich python -c "from rich.console import Console; Console().print('Hello', style='bold red')"`
• IMPORTANT: Think hard about your calculations ALWAYS double check your work as you go along.
• IMPORTANT: After you generate your report, review your numbers comprehensively with python. Also, make sure you write emojis and not unicode characters.
• In your finance_report.yaml file, do not use yaml anchors or aliases and do not use !!python tags. Write everything out as primitive types even if it means duplicating data.

Variables

DROPPED_FILE_PATH: [[FILE_PATH]] DROPPED_FILE_PATH_ARCHIVE: agentic_drop_zone/finance_zone/drop_zone_file_archive/ FINANCE_OUTPUT_DIR: agentic_drop_zone/finance_zone/finance_output/<date_time>/

• This is the directory where all processed files and reports will be saved
• The date_time is the current date and time in the format YYYY-MM-DD_HH-MM-SS

Output File Paths

CATEGORIZED_STATEMENT: FINANCE_OUTPUT_DIR/<date_time>/categorized_statement.csv

• The cleaned and properly categorized bank statement

FINANCE_REPORT: FINANCE_OUTPUT_DIR/<date_time>/finance_report.yaml

• The comprehensive financial analysis report in YAML format

SPENDING_PIE_CHART: FINANCE_OUTPUT_DIR/<date_time>/spending_by_category.png

• Pie chart visualization of spending by category

BALANCE_LINE_CHART: FINANCE_OUTPUT_DIR/<date_time>/balance_over_time.png

• Line chart showing account balance progression over time

Spending Thresholds (per category monthly spending)

LOW_SPENDING_THRESHOLD: 500

• Categories under this amount get 💰 emoji

MODERATE_SPENDING_THRESHOLD: 1000

• Categories between LOW and MODERATE get 🔥 emoji

HIGH_SPENDING_THRESHOLD: 2000

• Categories between MODERATE and HIGH get 🔥🔥 emoji
• Categories over HIGH get 🔥🔥🔥 emoji

Individual Transaction Alerts

LARGE_TRANSACTION: 500

• Single transactions over this get 🚨 flag

UNUSUAL_TRANSACTION: 1000

• Single transactions over this get ⚠️ flag

MAJOR_PURCHASE: 2500

• Single transactions over this get 🔴 flag

Budget Warning Percentages

HOUSING_WARNING_PCT: 30

• Alert if housing > this % of monthly income

DINING_ENTERTAINMENT_WARNING_PCT: 20

• Alert if dining/entertainment > this % of total expenses

SHOPPING_WARNING_PCT: 15

• Alert if shopping > this % of total expenses

TRANSPORTATION_WARNING_PCT: 20

• Alert if transportation > this % of total expenses

SUBSCRIPTION_WARNING_PCT: 10

• Alert if subscriptions > this % of total expenses

Workflow

Setup Phase

• Create output directory: `mkdir -p FINANCE_OUTPUT_DIR/<date_time>/`
• Copy original file to preserve it: `cp DROPPED_FILE_PATH FINANCE_OUTPUT_DIR/<date_time>/original_statement.csv`
• Create working copy: `cp FINANCE_OUTPUT_DIR/<date_time>/original_statement.csv FINANCE_OUTPUT_DIR/<date_time>/categorized_statement.csv`

Analysis & Categorization Phase

• Read the working copy: `FINANCE_OUTPUT_DIR/<date_time>/categorized_statement.csv`
• For each transaction row:
• Check if category is missing or incorrect
• Apply categorization rules from "How to Categorize" section
• Track which categories need updating
• Use MultiEdit to update all categories at once in the working copy
• Verify all transactions now have appropriate categories

Calculation Phase

• Calculate totals:
• Total income = sum of all deposits
• Total expenses = sum of all withdrawals
• Net cash flow = income - expenses
• Group expenses by category and calculate:
• Total spending per category
• Number of transactions per category
• Percentage of total expenses per category
• Identify top 5 spending categories
• Identify top 5 largest individual transactions
• Count transactions exceeding alert thresholds

Report Generation Phase

• Create report file: `FINANCE_OUTPUT_DIR/<date_time>/finance_report.yaml`
• Generate visualization charts as PNG files (use matplotlib with optional seaborn for styling):

1. **Spending Pie Chart** (`FINANCE_OUTPUT_DIR/<date_time>/spending_by_category.png`):

• Use matplotlib or plotly to create a pie chart
• Show top 10 categories by spending amount
• Include percentages and dollar amounts on labels
• Use distinct colors for each category
• Title: "Monthly Spending by Category - [Month Year]"
• Figure size: 12x8 inches
• DPI: 150 for high quality
• Add legend with category names and amounts
• Explode the largest spending category slightly for emphasis
• Example command:

       uv run --with pandas --with matplotlib python -c "
       import pandas as pd
       import matplotlib.pyplot as plt
       # Read categorized data
       df = pd.read_csv('categorized_statement.csv')
       # Group by category and sum withdrawals
       # Create pie chart with top 10 categories
       # plt.figure(figsize=(12, 8))
       # plt.savefig('spending_by_category.png', dpi=150, bbox_inches='tight')
       "

2. **Account Balance Chart** (`FINANCE_OUTPUT_DIR/<date_time>/balance_over_time.png`):

• Create a line chart showing balance progression through the month
• X-axis: dates (formatted as MM/DD)
• Y-axis: running balance (formatted with $ and commas)
• Mark major transactions (>$1000) with red dots and annotations
• Add horizontal dashed line for starting balance
• Add horizontal dotted line for ending balance
• Include grid for better readability
• Title: "Account