SmartBudget

Grocery receipt scanning, budget tracking, and spending intelligence.

SmartBudget is a Python CLI toolkit designed to work alongside an AI agent. The agent handles LLM tasks (vision-based receipt extraction, item categorisation, meal suggestions), while the CLI handles data operations — storage, budget math, category lookups, and reporting.

Features

• Receipt ingestion — parse agent-extracted receipt JSON, store items with categories
• Budget tracking — weekly and monthly spending vs configurable budgets
• Auto-categorisation — 3-tier system: exact match, fuzzy match, agent-assisted
• Spending history — per-category breakdowns, trends, and alerts
• Meal suggestions — build context from purchased items for agent-generated meal ideas
• CSV import — bulk import from bank/store export files
• File watcher — monitor a directory for new receipt images

Usage

pip install -e .

# Check spending status
smartbudget status

# Ingest a receipt
smartbudget ingest receipt.json

# View unknowns needing categorisation
smartbudget unknowns

# Budget overview
smartbudget budget

# Spending history
smartbudget history --days 30

# Run self-tests
smartbudget selftest

Configuration

Copy .env.example and edit config/settings.yaml to set:

• Weekly/monthly budget limits (NOK)
• Category definitions
• Database path
• Watch directory for receipt images

Architecture

smartbudget/
  cli.py          # Typer CLI commands
  models.py       # Pydantic data models
  extractor.py    # Receipt parsing and validation
  categoriser.py  # 3-tier category resolution
  budget.py       # Budget calculations
  reporter.py     # Spending reports and history
  suggestions.py  # Meal suggestion context builder
  watcher.py      # File system monitor
  csv_import.py   # Bank/store CSV import
  db/             # SQLite connection and queries
  config/         # Settings loader

Tech

Python 3.10+ Typer Rich Pydantic SQLite Watchdog