Project Info

AI Personal Finance Assistant

Inspiration

In a world of constant online shopping, subscriptions, and one-click purchases, it's easier than ever to spend money without really noticing where it goes. Most people have dozens of recurring payments and hundreds of transactions every month, yet a bank statement is still just a long list of numbers. It tells you what you spent, but not why, or what patterns are hiding underneath. So, I wanted to build something that could change that. My goal was to build a project that is useful and easy to use, yet still powerful "under the hood". That's why I decided to unite AI and machine learning to create an app that gives people a clear understanding of their spending without requiring them to be finance experts or spend hours analyzing spreadsheets. It's a project I wanted to be meaningful from day one, something I'd genuinely use myself, and technically solid enough to be more than a weekend distraction.

What it does

AI Personal Finance Assistant analyzes a bank statement and uncovers the spending habits hidden behind the transactions. Users upload a bank export (.csv or .xlsx, up to 5 MB), and the app automatically processes it, groups merchants into meaningful spending patterns using K-means clustering, and identifies recurring spending behaviors. Then, GPT-5.6 gives each spending pattern a meaningful name and generates a concise explanation in plain English. Instead of simply saying that spending increased by 20% compared to last month, the app explains why it increased – whether it was due to subscriptions, recurring purchases, one-off expenses, or changes in spending habits. Users can compare their spending over the last month, three months, six months, or across their entire transaction history to understand how their finances evolve over time. How I built it The application is built entirely in Python, with Codex acting as a development partner throughout the project. Uploaded files are parsed into pandas DataFrames, merchant names are normalized, and a set of features is extracted for each merchant, including purchase frequency, average spending, timing regularity, and price consistency. Those features are clustered using scikit-learn's K-means algorithm to identify meaningful spending patterns. To protect user privacy, GPT-5.6 never receives raw transaction data. Instead, it only sees aggregated statistics for each cluster, which it uses to generate human-readable pattern names and personalized spending insights through the OpenAI API. Everything is presented through a responsive Streamlit dashboard with interactive Plotly visualizations, making the results easy to explore on desktop, tablet, and mobile devices. Challenges I ran into While building this project, I faced several challenges, but two stood out the most: Working around Streamlit's styling limitations. Streamlit is a great option for quickly building and deploying applications, especially for beginners, but customizing its appearance can be surprisingly difficult. The built-in charts are quite opinionated, and even something as simple as creating a donut chart with rounded segments required hours of experimenting, tweaking, and manually patching the underlying chart configuration. Making the AI provide real insights instead of obvious observations. Getting GPT to describe a chart is easy, yet it doesn't add much value. The real challenge was prompting it to identify genuinely useful patterns instead of repeating what users could already see. After a lot of experimentation, I focused the summaries on five key areas: the biggest spending change, subscriptions, recurring habits, unusual one-off expenses, and anything that deserves a closer look. Accomplishments that I'm proud of Building my first frontend application from scratch and turning it into a polished, fully functional product. Taking the project from a rough idea to a deployed application within the hackathon timeframe. Creating a clean, modern interface that focuses on insights rather than overwhelming users with numbers. Building an AI summary that explains why spending changed instead of simply describing the charts. Delivering a responsive dashboard that works well across desktop, tablet, and mobile devices. What I learned This was my first time building a frontend application from scratch and my first experience working with Codex as a true development partner rather than just a coding assistant. Along the way, I learned how to design and deploy an interactive Streamlit dashboard, apply K-means clustering to noisy real-world financial data, engineer meaningful features from transaction histories, and integrate GPT-5.6 to generate useful, human-friendly insights. Most importantly, I learned what it takes to turn an idea into a polished, working product in just a few days.

What's next

Downloadable PDF reports that users can save or share. Support for additional languages beyond English. A light theme alongside the current dark interface. Lightweight budgeting, allowing users to set spending targets for categories or patterns and receive alerts when they exceed them. AI-powered recommendations for unnecessary subscriptions and recurring expenses, with suggestions on where users could save money. Long-term spending forecasts and trend predictions for users with enough historical data.

💰 AI Personal Finance Assistant

See the patterns behind your spending · Apps for Your Life

🚀 See it in action

Open the live app to explore your spending patterns instantly with an interactive dashboard that turns raw transactions into clear, actionable insights.

🎯 The Problem

Bank statements hide more than they show. They tell you every transaction, but not the story behind your spending. Recurring subscriptions, everyday purchases, and hidden spending patterns are buried in hundreds of line items, making it difficult to understand where your money actually goes.

💡 The Solution

AI Personal Finance Assistant transforms raw transaction data into clear spending insights. By combining machine learning with GPT-5.6, it discovers meaningful spending patterns and explains them in plain English, helping you to understand your spending in just a few seconds.

✨ Core Features

Feature	Description
Reveal the habits behind the transactions	The app identifies up to five spending patterns using frequency, typical amount, timing, and consistency, not merchant names alone
Turn data into a clear story	GPT-5.6 gives each pattern a meaningful label and writes a plain-English summary
See change over time	Compare the last month, three months, six months, or your full history without redefining the underlying patterns
Use the app anywhere	Explore your spending patterns comfortably on a computer, tablet, or mobile phone
Keep your data private	Files are processed in memory and never stored. AI receives only aggregated pattern evidence. Never raw transaction history

🚀 Quick Start

Local Development

# Install dependencies
uv sync --group dev

# Run offline (with mock analysis)
MOCK_LLM=true uv run streamlit run app.py

# Run with GPT-5.6 (requires OPENAI_API_KEY)
OPENAI_API_KEY=sk-... uv run streamlit run app.py

Demo data is bundled (data/spending_demo.csv). No upload needed to explore.

Testing

# Run all 51 tests offline (no OpenAI calls)
MOCK_LLM=true uv run pytest

# Run a specific test
MOCK_LLM=true uv run pytest tests/test_llm.py::test_summary_with_question_rejected -v

Deployed Instance

Visit your-ai-personal-finance-assistant.streamlit.app. The app redeploys automatically when changes are pushed to main. Its OPENAI_API_KEY is securely configured in Streamlit Cloud Secrets.

🧠 How Codex Contributed to The Final Result

Product development - Codex turned the initial idea into a finished personal-finance product.
Engineering - Codex helped to write and improve the code behind the Streamlit app, and detect the bugs.
Accuracy & consistency - Codex tracked changes across code and documentation, keeping updates synchronized, and reducing the risk of inconsistencies as the project evolved.
App design - Codex supported continuous design iteration across the dashboard layout, charts, responsive desktop/mobile experience.
Demo data - Codex helped to create a realistic demo dataset to showcase features without using sensitive data.
Project delivery - Codex helped to prepare the README, licence, repository structure, etc.

🏆 How GPT-5.6 Shaped the Product

Pattern labels - GPT-5.6 turns the raw evidence into meaningful labels based on spending frequency, typical amount, and consistency.
Spending summary - GPT-5.6 translates the analysis into five practical insights: the biggest change, subscriptions, recurring habits, one-off expenses, and items worth a closer look.
Clear language - GPT-5.6 presents insights in natural, conversational language instead of technical terminology.
Currency-aware results - GPT-5.6 uses the currency detected from the uploaded statement so amounts are presented in the user’s original currency.
Natural merchant names - GPT-5.6 makes merchant references human-friendly instead of repeating raw bank-statement descriptions.

🎥 Demo Video

📺 Watch the Demo on YouTube

The demo covers:

The hidden-spending problem and why it matters
How Codex was used in the development workflow
Why pairing statistical clustering with GPT-5.6 is the right approach
Live walkthrough with synthetic demo data (patterns, spending habits, AI summary)

🧩 Built With

OpenAI GPT-5.6 · Python 3.11 · Streamlit · Pandas · scikit-learn · Plotly · pytest

📄 License

The code in this repository is licensed under the Apache License, Version 2.0 – see LICENSE for the full text.

Built for OpenAI Build Week · Apps for Your Life

Analysis

Compare with all teams

View

Metric

Olya
11

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

OpenAIIn code
PythonIn code
StreamlitIn code

3 of 3 appear in the indexed code.

AI coding agents

No AI coding agent signals were found in this repository.

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

206 KB

Source files

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.