receipt-raccoon

Extracts structured data from receipt text (OCR/photo description) and generates monthly spending reports. Parses merchant, date, line items, tax, total, and category. Produces summary stats: top merchants, category breakdown, total spend.

Never manually enter receipt data again. Feed it receipt text and get clean structured data out.

When to use

• The user provides receipt text from OCR, a photo description, or copy-paste.
• The user wants to track expenses from receipts.
• The user wants a monthly or category-based spending summary.
• The user wants to export receipt data as structured JSON.

How it works

1. Receive raw receipt text (multiline string).
2. Run scripts/receipt_parser.py parse --text "..." or pipe via stdin.
3. The script extracts: merchant name, date, line items with prices, subtotal, tax, total.
4. Each item is categorised using keyword matching (groceries, dining, electronics, etc.).
5. Store parsed receipts in a JSONL ledger file for accumulation.
6. Run scripts/receipt_parser.py report --ledger receipts.jsonl to generate summary stats.

Usage

Parse a single receipt

bash

# From command line argument
python3 scripts/receipt_parser.py parse --text "$(cat receipt.txt)"

# From stdin
cat receipt.txt | python3 scripts/receipt_parser.py parse

# From a file
python3 scripts/receipt_parser.py parse --file receipt.txt

Accumulate receipts

bash

# Parse and append to a ledger
python3 scripts/receipt_parser.py parse --file receipt.txt --append receipts.jsonl

Generate reports

bash

# Summary of all receipts in ledger
python3 scripts/receipt_parser.py report --ledger receipts.jsonl

# Filter by month
python3 scripts/receipt_parser.py report --ledger receipts.jsonl --month 2024-01

# JSON output
python3 scripts/receipt_parser.py report --ledger receipts.jsonl --json

Output format

Parsed receipt JSON:

json

{
  "merchant": "WHOLE FOODS MARKET",
  "date": "2024-01-15",
  "items": [
    {"name": "ORGANIC BANANAS", "price": 2.99, "category": "groceries"},
    {"name": "ALMOND MILK", "price": 3.49, "category": "groceries"}
  ],
  "subtotal": 6.48,
  "tax": 0.52,
  "total": 7.00,
  "currency": "USD"
}

Report output includes:

• Total spend, receipt count, average receipt
• Top merchants by spend
• Category breakdown with percentages
• Monthly trend
• Tax total

Categorisation

Items are categorised using keyword matching against these categories:

Category	Example keywords
Groceries	milk, bread, eggs, vegetable, fruit, meat, cheese
Dining	burger, pizza, coffee, restaurant, cafe, taco
Electronics	cable, charger, battery, phone, laptop, usb
Clothing	shirt, pants, shoes, dress, jacket
Health	pharmacy, medicine, vitamin, bandage
Household	soap, detergent, paper, cleaning
Transport	gas, fuel, uber, taxi, parking
Entertainment	movie, ticket, game, concert
Other	(fallback)

Files

• scripts/receipt_parser.py — main parser and report generator
• references/categories.md — full category keyword reference
• references/receipt_formats.md — notes on supported receipt formats