💸 SpendLens — AI-Powered Spending Intelligence

Upload your bank CSV. Ask questions in plain English. Get instant charts and GPT-powered insights.

---

What It Does

Most people have no idea where their money actually goes. SpendLens fixes that.

• Upload any bank CSV export (Chase, BoA, Wells Fargo, Mint, etc.)
• Instantly see spending by category, by month, and over time
• Ask anything in plain English — "Where did I overspend in February?", "What's my daily average?", "Which subscriptions should I cut?"
• Get actionable answers powered by GPT-4o-mini with your real data as context

Demo

▶ Try the live demo →
(Uses built-in sample data — no upload needed)

---

Setup

1. Clone the repo

git clone https://github.com/yourusername/spendlens.git
cd spendlens

2. Install dependencies

pip install -r requirements.txt

3. Run the app

streamlit run app.py

4. Open in browser

http://localhost:8501

---

How to Use

1. Get your bank CSV — Most banks let you export transaction history as CSV from the account activity page
2. Upload it to SpendLens (or hit "Use sample data" to try immediately)
3. Explore the charts — spending by category (donut), monthly totals (bar), and cumulative over time (area)
4. Add your OpenAI API key to unlock the Q&A feature
5. Ask questions — use the quick-question buttons or type anything

---

CSV Format

SpendLens auto-detects column names, but works best with:

Column	Description
Date	Transaction date
Description	Merchant or memo
Amount	Negative = expense (most bank formats)
Category	Optional — SpendLens handles uncategorized too

Compatible with: Chase, Bank of America, Wells Fargo, Capital One, Mint CSV exports.

---

How I Built It

The Goal: Make personal finance analysis accessible — no spreadsheets, no manual categorization, just upload and understand.

AI Tools Used:

• Codex / GPT-4o-mini — Powers the natural language Q&A layer. The model receives a structured JSON summary of the user's transactions and answers questions with specific numbers and actionable tips.
• GitHub Copilot — Used throughout development for boilerplate, Plotly chart configs, and CSS styling.

Tech Stack:

• Streamlit — Web app framework (zero frontend code needed)
• Pandas — CSV parsing and transaction aggregation
• Plotly — Interactive charts (donut, bar, area)
• OpenAI Python SDK — GPT-4o-mini for Q&A

What I Learned:

• Prompt engineering matters a lot for financial Q&A — giving the model a pre-computed JSON summary (rather than raw transactions) makes responses much faster and more accurate
• Streamlit's session state makes it easy to build multi-turn conversations
• Auto-detecting CSV column names (different banks use different headers) was the trickiest parsing challenge

---

Project Structure

spendlens/
├── app.py              # Main Streamlit app
├── requirements.txt    # Dependencies
├── sample_data.csv     # Sample transactions for demo
└── README.md

---

Deployment

Deploy free on Streamlit Community Cloud:

1. Push to GitHub
2. Go to share.streamlit.io
3. Connect your repo → deploy

---

License

MIT — free to use, modify, and share.

---

Built with Python + OpenAI for the OpenAI Codex Student Lab