local-budget（地方预算）

Local Budget

Analyze bank/credit card CSV exports, categorize transactions, compare against budgets, and generate clean markdown reports for Obsidian.

Workflow Overview

1. Parse — run parse_csv.py to normalize raw CSVs into a unified JSON format
2. Categorize — run categorize.py to get LLM-ready JSON with suggested categories; review/adjust
3. Report — run report.py to generate a markdown spending report

All scripts live in scripts/. Budget config and sample data in assets/. See references/csv-formats.md for supported formats and references/categories.md for category customization.

Step 1: Parse CSV

python3 scripts/parse_csv.py <input.csv> [--format chase|boa|generic] [--output transactions.json]

• Auto-detects format if --format is omitted (checks header columns)
• Outputs a unified JSON array of transaction objects
• Each transaction: { "date": "YYYY-MM-DD", "description": str, "amount": float, "type": "debit"|"credit", "original_category": str|null }
• Debits are positive amounts; credits (refunds/income) are negative
• Handles multiple date formats: MM/DD/YYYY, YYYY-MM-DD, MM/DD/YY
• Skips rows with missing date or amount; logs warnings to stderr

If the user's bank isn't auto-detected, check references/csv-formats.md for column mappings and use --format generic with the appropriate flag, or add a new format.

Step 2: Categorize Transactions

python3 scripts/categorize.py transactions.json [--budget assets/sample-budget.json] [--output categorized.json]

• Outputs a JSON file with each transaction tagged with a suggested category based on description keyword matching
• The LLM (you) should review the output and adjust categories before generating the report
• Default categories: Housing, Food & Dining, Transportation, Utilities, Entertainment, Shopping, Health, Subscriptions, Income, Other
• To adjust: edit the JSON directly, or tell the user which transactions look miscategorized and confirm corrections
• See references/categories.md for the keyword-matching logic and how to customize

LLM review step: After running categorize.py, scan the output for anything in "Other" or with low-confidence keywords. Ask the user to confirm or correct those entries before proceeding.

Step 3: Generate Report

python3 scripts/report.py categorized.json [--budget assets/sample-budget.json] [--output report.md]

• Generates a markdown report with:

- Monthly summary (total in/out) - Spending by category with budget vs. actual comparison - Top 10 merchants by spend - Month-over-month trend if multiple months present in the data - Overage alerts for categories that exceed budget

• If --budget is omitted, report shows actuals only (no budget comparison)
• Output is Obsidian-compatible markdown with frontmatter

Budget Config

Budget is defined in a JSON file. See assets/sample-budget.json for a realistic example.

{
  "monthly_budgets": {
    "Housing": 1800,
    "Food & Dining": 600
  }
}

Common Tasks

"Analyze my Chase export" → parse_csv.py chase_export.csv --format chase --output tx.json → categorize.py tx.json --output cat.json → Review categories, then report.py cat.json --budget assets/sample-budget.json

"Show me my spending for March" → Parse and categorize the CSV, then filter by month in report.py (it auto-groups by month)

"I went over budget on dining" → Run the full pipeline; report.py flags overage categories with ⚠️

"Add a new bank format" → See references/csv-formats.md for the column mapping spec

"Customize categories" → See references/categories.md to edit keyword lists or add new categories

File Locations

Store CSVs and JSON outputs wherever the user prefers. Default working directory is wherever the command is run. Suggest keeping exports in a dedicated folder like ~/finances/exports/.

Reports can be saved directly to the Obsidian vault:

python3 scripts/report.py categorized.json --output ~/path/to/vault/finance/2024-03-budget.md