README.md

---
title: BudgetBuddy – Personal Finance Agent
emoji: 💰
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
short_description: Autonomous Personal Finance Agent
---



# BudgetBuddy — Autonomous Personal Finance Agent (Hugging Face Space ready)

This repository contains a Gradio app that parses bank CSVs, auto-categorizes transactions, produces summaries, and predicts next-month expenses per category.

## What's included
- `app.py` — Gradio app entrypoint
- `finance_utils.py` — helpers for parsing, categorization, summary, prediction
- `requirements.txt` — Python dependencies
- `data/` — place your CSV files here (sample datasets can be included)

## How to use on Hugging Face Spaces
1. Create a new Space (Gradio) on Hugging Face: https://huggingface.co/new-space
2. Choose **Gradio** and set repo visibility (public/private as you like).
3. Upload the contents of this folder into the Space repository (you can drag-and-drop files in the web UI or push via git).
4. Option A — Bundled datasets: put your CSVs in the `data/` folder of the repo before deployment (they will be available to the app at startup).
5. Option B — Runtime upload: users can upload CSVs directly through the app UI using the file uploader.
6. Start the Space. The Gradio app will appear on the Space page.

## External datasets and sources (suggestions)
You can use your bank's CSV export or any of these public datasets to test:
- Kaggle — Personal Finance datasets (search: "personal finance transactions" on https://kaggle.com)
- "Personal Finance Dataset" — sample CSVs (you may replace them with your own)
- Open banking sandbox CSVs (for larger tests)

## Notes on real data
- Use your own bank CSVs (download export from your bank/UPI/wallet). Column names differ across banks; `finance_utils.py` applies heuristics to handle variations.
- Remove or anonymize personal identifiers before sharing publicly.

## Uploading CSVs after deployment
- Use the web UI file uploader in the Gradio app to upload multiple CSVs at runtime.
- Or commit CSVs into the `data/` folder of the repo (recommended for demo reproducibility).