Upload your real bank statement → get an instant financial dashboard and chat with an AI advisor grounded in your actual spending.
FinGenius started life in 2024 as a Gemini-powered Colab notebook exploring five Gen AI capabilities. It worked — but it lived inside cells you had to run top to bottom. This repository is the rebuild: the same five capabilities, now wired into a real, deployable full-stack application with a polished dashboard, a live AI advisor, real bank-statement parsing, per-user isolation, and PII redaction.
From a notebook nobody could use → to a product you open in a browser.
Click to watch on Google Drive. (GitHub can't embed an inline player for Drive videos.)
- 📥 Upload a real bank statement (CSV or Excel) — it auto-detects the format, skips the account-info preamble, handles separate Debit/Credit columns, day-first dates, and comma-formatted amounts. Tested against State Bank of India (SBI) statements.
- 🏷️ Automatic categorization — extracts the merchant/payee from messy UPI strings
(
WDL TFR UPI/DR/.../Blinkit/...→ Blinkit) and categorizes it. Common Indian merchants match a free keyword map; only unknowns hit the LLM (capped per upload to bound cost). - 💱 Currency-aware — reads the statement's currency (e.g.
INR) and renders the whole dashboard in ₹ with Indian digit grouping. - 📊 Live dashboard — KPIs, cash-flow trend, savings rate, 50/30/20 budget, spending by category, and an interactive investment-growth calculator.
- 💬 AI advisor — an always-visible chat rail grounded in your numbers. Ask "where's my money going?", "what's my biggest expense?", "where can I cut back?" and it answers from your real data, plus does semantic search over your transactions.
- 🔒 Private & isolated by design — see Security & Privacy.
flowchart LR
subgraph Browser
UI["Dashboard<br/>KPIs, charts, categories"]
Chat["AI Advisor<br/>sticky chat rail"]
end
subgraph Server["FastAPI - server.py"]
Session["Session cookie<br/>HttpOnly, 256-bit, per-user"]
Ingest["Statement ingest<br/>CSV/XLSX, debit/credit<br/>day-first dates, INR detect"]
Redact["PII redaction<br/>account and ref numbers stripped"]
Snapshot["Dashboard snapshot<br/>KPIs, budget, cash flow"]
end
subgraph Brain["LangGraph ReAct Agent"]
T1["Calculators"]
T2["RAG lookup"]
T3["Categorize"]
T4["Semantic search"]
end
OpenAI["OpenAI<br/>gpt-4o-mini + embeddings"]
Chroma[("Chroma<br/>knowledge base")]
UI -->|upload| Ingest
Ingest --> Snapshot
Snapshot --> UI
Chat -->|chat| Session
Session --> Brain
Brain --> T1
Brain --> T2
Brain --> T3
Brain --> T4
Brain -->|grounded and redacted| Redact
Redact --> OpenAI
Ingest -.->|merchant redacted| OpenAI
T2 --> Chroma
T4 -->|embed search| OpenAI
Flow: the browser holds only a server-issued session cookie. Uploads are normalized and categorized server-side, then a snapshot drives the dashboard. The chat grounds a LangGraph agent in your data and routes everything through a redaction layer before it reaches OpenAI.
All five are wired into the LangGraph agent as callable tools, so the conversational advisor can reach any of them on demand.
| # | Capability | Implementation | Agent tool |
|---|---|---|---|
| 1 | Structured Output | Pydantic with_structured_output → typed TransactionCategory |
categorize_transaction |
| 2 | RAG | Chroma vector store over a financial knowledge base | financial_knowledge_lookup |
| 3 | Embeddings | OpenAI embeddings + cosine similarity over your statement | find_similar_transactions |
| 4 | Function Calling | 5 financial calculators (budget · emergency fund · debt · investment · loan) | calculate_* |
| 5 | Agents (LangGraph) | create_react_agent + memory, orchestrating all of the above |
(the advisor itself) |
| Layer | Technology |
|---|---|
| LLM | OpenAI gpt-4o-mini (configurable) |
| Agent framework | LangChain + LangGraph (ReAct agent with tool calling + memory) |
| Embeddings | OpenAI text-embedding-3-small |
| Vector store | ChromaDB (langchain-chroma) |
| Backend | FastAPI + Uvicorn |
| Data | pandas · NumPy · scikit-learn · openpyxl |
| Frontend | Single-file dashboard (vanilla HTML/CSS/JS, no build step) |
Prerequisites: Python 3.10+ and an OpenAI API key.
# 1. Clone
git clone https://github.com/anujdevsingh/financial_genius_agent.git
cd financial_genius_agent
# 2. Install
pip install -r requirements.txt
# 3. Add your key
cp .env.example .env # then edit .env and set OPENAI_API_KEY
# 4. Run the dashboard
uvicorn server:app --reload --port 8000
# open http://localhost:8000Click Upload statement, pick your bank's CSV/Excel export, and the dashboard + advisor update to your real data. No upload? It runs on a built-in sample dataset.
Simpler alternatives:
python main.py # terminal chat with the agent
streamlit run app.py # basic Streamlit UIThe first run builds a local Chroma vector store from the knowledge base (cached in
.chroma/).
The importer is built for real, messy statements, not just clean CSVs:
- Formats:
.csv,.xlsx,.xls - Preamble handling: automatically finds the real transaction table below account-info rows
- Column aliases:
Date/Transaction Date,Narration/Particulars/Details,Withdrawal Amt./Deposit Amt.,Debit/Credit,Amount, … - Debit/Credit split → single signed amount (debit = spend, credit = income)
- Day-first dates (
01/03/2026→ 1 March) and comma amounts (1,250.00) - Encoding fallback (UTF-8 → cp1252 for Windows-exported bank CSVs)
- UPI/IMPS merchant extraction + Indian merchant keyword categorization
Minimum required columns: a date, a description, and either an amount or debit/credit columns.
This is a public-demo-ready app, so isolation and privacy were designed in:
- 🔑 Server-issued sessions — a cryptographically strong (256-bit) HttpOnly cookie. The server never trusts a client-supplied id, so no one can guess or set another user's session. Each visitor's dashboard, chat, and search are fully isolated.
- 🔒 PII redaction before the LLM — account numbers, customer/reference IDs, and UPI VPAs are stripped from everything sent to OpenAI (chat grounding, categorization, and the semantic-search corpus). Merchant names and amounts are kept so advice stays useful; the account header is discarded on import and never leaves your machine.
- 🧾 In-memory only — uploaded statements live in server RAM keyed to your session, never written to disk or a database.
- ⏲️ Auto-expiry — a statement is purged after 30 min of inactivity (configurable), so sensitive data doesn't linger and idle sessions don't leak memory.
- 🚦 Rate limiting + daily budget cap — per-session limits stop spam, and a global daily "LLM-unit" cap bounds total OpenAI spend even across many sessions. All tunable via env vars.
The repo includes a render.yaml for one-click Render deploys:
- Push to GitHub and create a Render Blueprint from the repo.
- Set
OPENAI_API_KEYas an environment variable in the Render dashboard. - Deploy → you get a public
https://…onrender.comURL.
No login = your API key pays for every visitor. Before exposing it publicly, set a hard spending limit on your OpenAI account. For a portfolio, the launch video + this repo are the always-on showcase; bring the live demo up on demand.
| Variable | Default | Purpose |
|---|---|---|
OPENAI_API_KEY |
— | Your OpenAI key (required) |
FINGENIUS_CHAT_PER_MIN |
15 |
Max chat messages per session per minute |
FINGENIUS_UPLOAD_PER_MIN |
5 |
Max uploads per session per minute |
FINGENIUS_DAILY_LIMIT |
600 |
Global daily LLM-unit cap (chat = 1, upload = 10) |
FINGENIUS_SESSION_TTL_MIN |
30 |
Minutes of inactivity before an upload is auto-purged |
FINGENIUS_CHAT_MODEL |
gpt-4o-mini |
OpenAI chat model |
For a tight public demo, lower FINGENIUS_DAILY_LIMIT (e.g. 150) and FINGENIUS_SESSION_TTL_MIN
(e.g. 15) — together with your OpenAI account spending cap, this keeps cost firmly bounded.
financial_genius_agent/
├── fingenius/ # Application package
│ ├── config.py # Model config + LLM/embedding factories
│ ├── privacy.py # PII redaction before any LLM call
│ ├── data/ # Sample transactions + financial knowledge base
│ ├── analysis/ # Categorization (structured output) + embeddings
│ ├── rag/ # Chroma knowledge base + retriever
│ ├── tools/ # Agent tools: 5 calculators, RAG lookup,
│ │ # categorize, per-session semantic search
│ ├── dashboard.py # KPIs / budget / cash flow snapshot (+ advisor grounding)
│ └── agent/ # LangGraph conversational advisor (graph.py)
├── server.py # FastAPI server: sessions, upload, dashboard, chat
├── web/index.html # Single-file dashboard + AI chat rail
├── main.py # CLI chat entry point
├── app.py # Streamlit UI
├── render.yaml # One-click deploy config
├── requirements.txt
├── .env.example
└── fingenius-notebook-gemini-agent.ipynb # Original Colab notebook (the origin story)
The original fingenius-notebook-gemini-agent.ipynb is kept in the repo as the project's
starting point — a Gemini-based walkthrough of the five Gen AI capabilities. Everything in
fingenius/ is the productionized rebuild of those ideas on an OpenAI + LangGraph stack.
MIT — see LICENSE.