CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Python tools for BAC Costa Rica credit card statement processing:

bac_extract.py: Extracts transactions from statement PDFs to JSON
bac_analyze.py: Analyzes JSON output with categorization and graphs

Dependencies

pdfplumber (>=0.10.0) - PDF extraction
matplotlib (>=3.5.0) - graphs (optional, only for bac_analyze.py --graph)

Commands

# Run tests
python testStatements/run_tests.py

# Extract transactions from PDF
python bac_extract.py statement.pdf --pretty
python bac_extract.py statement.pdf -o output.json -v

# Analyze transactions (supports multiple JSON files)
python bac_analyze.py transactions.json
python bac_analyze.py *.json --graph all
python bac_analyze.py *.json --graph bar -o spending.png
python bac_analyze.py *.json --categories my_categories.json

Architecture

bac_extract.py

Extraction pipeline:

Validates PDF is a BAC statement (is_bac_statement)
Iterates pages line-by-line, detecting section boundaries via SECTIONS dict patterns
Parses transactions matching TRANSACTION_PATTERN regex
Outputs card holders, transactions by section, and summaries

Key data structures:

SECTIONS: Maps section IDs (B/D/E) to start/end regex patterns and output keys
SPANISH_MONTHS: Spanish month abbreviations for date parsing

bac_analyze.py

Analysis pipeline:

Loads transactions from one or more JSON files (purchases only)
Categorizes by matching description against patterns in categories.json
Aggregates by category and month, keeping CRC/USD separate
Outputs text summary and optional graphs (bar/pie/timeline/all)

1.7 KiB Raw Blame History