Expense CSV categorizer with editable rules

What it does

Turns card and bank statements into numbers you can use for a household budget or expense summary.

• Finds the header row automatically, even in Shift_JIS files with card-name lines above the table, and maps date, merchant, amount and deposit columns
• Reads amounts written with commas, a yen sign or the kanji yen suffix, triangle minus signs and parentheses; spending is positive, refunds and income are negative
• Categorizes with keywords or regular expressions from a CSV rules file. Full-width/half-width and case differences are ignored, so half-width katakana merchant names match too
• Ships with starter rules for common Japanese convenience stores, supermarkets, transit IC cards, mobile carriers and subscriptions
• Writes monthly totals per category (spent, refunds or income, net) and records which rule matched each row
• Groups unmatched rows by merchant in unknown.csv

How to use

python scripts/expense_categorize.py card.csv bank.csv --rules my_rules.csv --out-dir out/

The agent proposes categories for unknown merchants, adds the ones you confirm to your rules file, and re-runs. Each round leaves fewer unknown rows.

Requirements

• Python 3 (standard library only)

Caveats

• Statement files and the rules file are only read, never changed.
• Categories whose name starts with _ are excluded from totals; use them for card bill payments and transfers between your own accounts to avoid double counting.
• Starter rules are a starting point. Short keywords can match the wrong merchant, so check the recorded rule.
• Totals use the transaction date month. This is not tax or accounting advice.