Expense Tracker

Trigger

When Von sends a photo of a receipt, transaction screenshot, or mentions logging an expense.

Workflow

1. Parse the Image

Use vision_analyze to extract transaction details:

Question: "Extract all transaction details from this image. Look for: date, merchant/vendor name, total amount, currency, payment method, and individual items if visible. Format as JSON."

2. Categorize the Transaction

Apply categories based on merchant/item keywords:

Important Merchant Mappings:

• GADC = Golden Arches Development Corporation = McDonald's Philippines franchise. Appears as "GADC AYLAZMBGACITY" etc. on card terminals. Always categorize as Food/Dining. | Utilities | PLDT, Meralco, water, electric, internet, phone | | Entertainment | Netflix, Spotify, cinema, gaming, subscription | | Shopping | Mall names, clothing brands, electronics, retailers | | Health | Pharmacy, clinic, hospital, medicine, Watsons | | Education | School, tuition, books, supplies | | Income | Salary, transfer in, deposit, credit | | Bills | Loan, insurance, credit card payment | | Transfers | Bank transfer, send money, withdrawal | | Other | Default if no match |

Merchant Abbreviations

Many Philippine merchants appear as abbreviations on receipts. Map these correctly:

Philippine Mall Categorization:

• KCC Mall, SM Mall, Gaisano, Robinsons — usually grocery/shopping
• Ask Von if category is unclear (Groceries vs Shopping)

When parsing receipts, cross-reference these abbreviations to ensure accurate categorization.

3. Create/Update Monthly Spreadsheet

File naming: {YYYY-MM}_Expenses.xlsx

Example: 2026-04_Expenses.xlsx

Sheets:

1. Transactions — All expense entries
2. Summary — Monthly totals by category
3. Daily — Daily spending breakdown

4. Transaction Sheet Structure

Implementation

Logging a Transaction

ALWAYS use the helper script - never create or modify Excel files directly:

python /Users/von/von_ai_agents/Von/Finance/log_expense.py \
  --date 2026-04-11 \
  --merchant "Coffee Bean" \
  --amount 350 \
  --category "Food/Dining" \
  --description "Cafe latte, pastry" \
  --payment "Card" \
  --notes "Meeting with client"

For today's date, use --today instead of --date:

python /Users/von/von_ai_agents/Von/Finance/log_expense.py \
  --today \
  --merchant "Seven-Eleven" \
  --amount 150 \
  --category "Groceries"

The script automatically:

• Creates new monthly file if it doesn't exist
• Appends to existing transactions (NEVER overwrites)
• Updates Summary and Daily sheets

Parsing Receipt/Screenshot

When Von sends an image:

1. Extract with vision_analyze:

   • Date (convert to YYYY-MM-DD)
   • Merchant name
   • Total amount
   • Payment method (if visible)
   • Individual items (if detailed receipt)
   • Any transaction ID or reference

2. Auto-categorize based on merchant names and items

3. Confirm with Von if category is unclear:

   "Got it — ₱350 at Coffee Bean on April 1. Category: Food/Dining. Correct?"
   

4. Append to monthly file

5. Confirm saved:

   ✅ Logged: ₱350.00 — Coffee Bean (Food/Dining)
   📁 April 2026 total: ₱12,450.00
   

Monthly Summary

When Von asks for expense summary:

def get_monthly_summary(filepath):
    wb = openpyxl.load_workbook(filepath)
    ws = wb["Summary"]
    
    # Return category totals
    return {
        "Food/Dining": 4500.00,
        "Transportation": 3200.00,
        "Shopping": 8500.00,
        # ...
        "Total Expenses": 35000.00,
        "Total Income": 50000.00,
        "Net": 15000.00
    }

Edge Cases

Multiple transactions in one image

• Parse each transaction separately
• Add all to the sheet with individual confirmaations

Unclear date

• Use current date as default
• Ask Von to confirm: "No date visible — using today (April 1). Correct?"

Currency conversion

• If foreign currency, note original amount
• Convert to PHP using current rate (ask Von or use rough estimate)
• Log both amounts in Notes

Missing merchant name

• Extract from context or ask Von
• Use "Unknown" as fallback, note for correction

Querying Expenses

When Von asks to see expenses for a specific date or period:

Single day:

python3 -c "
from openpyxl import load_workbook

wb = load_workbook('/Users/von/von_ai_agents/Von/Finance/YYYY-MM_Expenses.xlsx')
ws = wb['Transactions']

target_date = 'YYYY-MM-DD'
total = 0
items = []

for row in ws.iter_rows(min_row=2, values_only=True):
    if row[0] and str(row[0]).startswith(target_date):
        items.append({
            'merchant': row[2],
            'amount': row[5] if row[5] else 0,
            'category': row[4] if row[4] else '',
        })
        total += row[5] if row[5] else 0

if items:
    for item in items:
        print(f\"- {item['merchant']}: {item['amount']:,.2f} ({item['category']})\")
    print(f'Total: {total:,.2f} PHP')
"

Column indices (0-based):

• 0: Date (YYYY-MM-DD)
• 1: Time (HH:MM or None)
• 2: Merchant
• 3: Description
• 4: Category
• 5: Amount (numeric)
• 6: Currency
• 7: Payment
• 8: Type
• 9: Notes

Response Format

After logging expense:

✅ Logged: ₱{amount} — {merchant} ({category})
📅 {date}
📁 {month} total: ₱{monthly_total}

If clarification needed:

📋 Parsed: ₱{amount} at {merchant}
❓ Category unclear — is this Food, Shopping, or something else?

Files

• /Users/von/von_ai_agents/Von/Finance/2026-04_Expenses.xlsx
• /Users/von/von_ai_agents/Von/Finance/2026-03_Expenses.xlsx
• etc.

Notes

• Keep one file per month for easier tracking
• Preserve all raw data from images in Description field
• Amounts are always in the original currency (convert in Notes if needed)
• Category can be changed manually — keep a note of miscategorizations for future improvement37:["$","$L3c",null,{"content":"$3d","frontMatter":{"name":"expense-tracker","version":"1.1.0","changelog":[{"Sat Apr 11 2026 00:00:00 GMT+0000 (Coordinated Universal Time)":"Fixed file overwrite bug - now checks existing file before creating, uses dedicated script"},{"Wed Apr 01 2026 00:00:00 GMT+0000 (Coordinated Universal Time)":"Initial version"}],"description":"Track expenses from receipts and transaction screenshots. Parse images, extract transaction details, and log to monthly Excel spreadsheets."}}]