FinanceGPT 💰

Your AI-Powered Personal CPA

Connect bank accounts • Upload tax forms • Get instant insights

Quick Start • Features • Example Prompts • Privacy • Contributing

🚀 Quick Start

Choose your preferred setup method:

Option 1: All-in-One Docker (Easiest)

# Clone and run with a single container
git clone https://github.com/yourusername/FinanceGPT.git
cd FinanceGPT

# Copy environment file and add your API keys
cp .env.example .env
# Edit .env with your OPENAI_API_KEY, PLAID_CLIENT_ID, PLAID_SECRET

# Start FinanceGPT
docker compose -f docker-compose.quickstart.yml up -d

🎉 Open http://localhost:3000 — You're done!

Option 2: Local Development (macOS)

# Clone the repository
git clone https://github.com/yourusername/FinanceGPT.git
cd FinanceGPT

# Start infrastructure (PostgreSQL, Redis)
docker compose up -d db redis electric

# Run the dev script (opens 3 terminal tabs automatically)
chmod +x dev.sh
./dev.sh

This starts:

🔧 Backend API on http://localhost:8000
🔄 Celery Worker for background tasks
🌐 Frontend on http://localhost:3000

Option 3: Full Docker Stack

# Clone the repository
git clone https://github.com/yourusername/FinanceGPT.git
cd FinanceGPT

# Configure environment
cp financegpt_backend/.env.example financegpt_backend/.env
# Edit .env with your API keys

# Build and run all services
docker compose up -d --build

# View logs
docker compose logs -f

🔐 Privacy-First Design

Your financial data is sensitive. FinanceGPT is built with privacy as a core principle:

Feature	How It Protects You
🔒 PII Masking	SSN and EIN are masked before any LLM call (`123-45-6789` → `XXX-XX-XXXX`). Your tax forms never expose sensitive IDs.
🏠 Self-Hostable	Run entirely on your own hardware. Your data never leaves your machine.
🤖 BYO Model	Use your own LLM (OpenAI, Anthropic, or local Ollama). No vendor lock-in.
🔐 Local Processing	Sensitive field extraction (SSN, EIN) happens locally—not via cloud APIs.
🗄️ Your Database	All data stored in your PostgreSQL instance. Export or delete anytime.
🚫 No Telemetry	Zero tracking, zero analytics, zero data collection.

# Example: How we handle your W2
raw_text = "SSN: 123-45-6789, Wages: $183,000"
masked_text = mask_pii_in_text(raw_text)  
# → "SSN: XXX-XX-XXXX, Wages: $183,000"
# Only masked_text is sent to the LLM

💬 Example Prompts

Just ask questions in plain English. FinanceGPT understands context.

💰 Income & Tax Questions

"How much did I earn in 2024?"
"What was my total federal tax withheld?"
"Will I get a tax refund this year?"
"Show me my W2 summary"
"What state taxes did I pay?"

📊 Spending Analysis

"How much did I spend on restaurants last month?"
"What are my recurring subscriptions?"
"Find all Amazon purchases over $100"
"What's my biggest expense category?"
"Show spending trends for the last 3 months"

💳 Credit Card Optimization

"Which card should I use for groceries?"
"Am I using the right credit card for travel?"
"How much rewards am I missing out on?"
"Optimize my credit card usage"

📈 Investment Portfolio

"How are my stocks performing today?"
"What's my portfolio return this year?"
"Is my allocation correct for my age?"
"Should I rebalance according to Bogleheads?"
"Can I harvest any tax losses?"

🏦 Account Overview

"What's my net worth?"
"Show all my account balances"
"How much do I have in savings?"
"What's my monthly cash flow?"

🌟 Features

🤖 AI-Powered Financial Advisor

Natural Language Queries: Ask questions about your finances in plain English
Smart Transaction Search: "How much did I spend on restaurants last year?"
Personalized Recommendations: AI-driven suggestions for saving money
Tax Form Analysis: Upload W2s, 1099s and get instant summaries

💳 Smart Credit Card Optimization

Rewards Maximization: Get the best card for each purchase category
Spending Pattern Analysis: Identify where you're leaving money on the table
Multi-Card Strategy: Optimize rewards across all your cards

📈 Investment Portfolio Management

Real-Time Performance: Track returns with live Yahoo Finance data
Time-Based Analysis: WoW, MoM, QoQ, YoY performance tracking
Tax Loss Harvesting: Find opportunities to reduce your tax bill
Rebalancing Recommendations: Compare to Bogleheads, Three-Fund Portfolio

📋 Tax Document Processing

Supported Forms: W2, 1099-INT, 1099-DIV, 1099-B, 1099-MISC, 1095-C
LLM-Powered Extraction: Accurate parsing with structured output
Tax Estimate: Calculate potential refund or amount owed
State Tax Support: Extracts state wages and withholdings

💰 Transaction & Spending Analysis

100+ Financial Institutions: Connect via Plaid
Subscription Detection: Find forgotten recurring charges
Category Analysis: Understand where your money goes
Historical Comparisons: Compare spending across time periods

🏗️ Architecture

Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 15, TypeScript, Tailwind	Modern web UI with server components
Backend	FastAPI, Python 3.11+	Async API with auto-generated docs
Database	PostgreSQL + pgvector	Relational + vector search
Task Queue	Celery + Redis	Background document processing
AI	LiteLLM	Provider-agnostic (OpenAI, Anthropic, Ollama)
Banking	Plaid API	100+ financial institution connections
Auth	Better Auth	OAuth 2.0, Google Sign-In

Project Structure

FinanceGPT/
├── financegpt_web/          # Next.js frontend
│   ├── app/                 # App router pages
│   ├── components/          # React components
│   └── lib/                 # Utilities
├── financegpt_backend/      # FastAPI backend
│   ├── app/
│   │   ├── agents/          # AI agents and tools
│   │   ├── parsers/         # Tax form parsers
│   │   ├── routes/          # API endpoints
│   │   └── tasks/           # Celery tasks
│   └── alembic/             # Database migrations
├── docker-compose.yml       # Full stack deployment
├── docker-compose.quickstart.yml  # All-in-one container
└── dev.sh                   # Local development script

📖 Configuration

Required Environment Variables

# LLM Provider (choose one)
OPENAI_API_KEY=sk-...
# or ANTHROPIC_API_KEY=sk-ant-...
# or GOOGLE_API_KEY=AIza...

# Plaid (for bank connections)
PLAID_CLIENT_ID=your_client_id
PLAID_SECRET=your_secret
PLAID_ENV=sandbox

# Security
SECRET_KEY=your-random-secret-key

Optional Configuration

# Document Processing
UNSTRUCTURED_API_KEY=...     # For PDF parsing
ETL_SERVICE=DOCLING          # Or UNSTRUCTURED

# Voice Features
TTS_SERVICE=local/kokoro
STT_SERVICE=local/base

🧪 Development

Running Tests

# Backend
cd financegpt_backend && pytest

# Frontend  
cd financegpt_web && pnpm test

Database Migrations

cd financegpt_backend
alembic revision --autogenerate -m "Description"
alembic upgrade head

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

Built on SurfSense, an open-source NotebookLM alternative
Financial data powered by Plaid
AI capabilities via LiteLLM

Made with ❤️ for anyone who's ever stared at a W2 wondering what it all means.

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github		.github
.rules		.rules
.vscode		.vscode
docs		docs
financegpt_backend		financegpt_backend
financegpt_browser_extension		financegpt_browser_extension
financegpt_web		financegpt_web
scripts/docker		scripts/docker
.DS_Store		.DS_Store
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.recurseml.yaml		.recurseml.yaml
.secrets.baseline		.secrets.baseline
Dockerfile.allinone		Dockerfile.allinone
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
dev.sh		dev.sh
docker-compose.quickstart.yml		docker-compose.quickstart.yml
docker-compose.yml		docker-compose.yml
financegpt.png		financegpt.png
run.sh		run.sh

License

manojag115/FinanceGPT

Folders and files

Latest commit

History

Repository files navigation