PredictWallet

AI Financial Early Warning System — Predicts cash crises 90 days before they hit.

59% of Americans can't survive a $1,000 emergency. PredictWallet sees the crisis before it happens and tells you exactly what to do about it.

What It Does

Upload your bank statement (CSV, PDF, or screenshot) and PredictWallet:

1. Categorizes every transaction using ML (LightGBM, 94%+ accuracy)
2. Forecasts your cash flow 30/60/90 days ahead (NeuralProphet)
3. Detects anomalies in your spending (Isolation Forest)
4. Scores your risk 0-100 with explainable factors
5. Alerts you before shortfalls, spending spikes, and bill collisions
6. AI Advisor answers questions grounded in YOUR actual data (RAG + Llama 3.1)

Quick Start

# Clone
git clone https://github.com/atharvajoshi01/PredictWallet.git
cd PredictWallet

# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --port 5001

# Frontend (new terminal)
cd frontend
npm install
npm run dev

Open http://localhost:3000

For AI Advisor (optional)

# Install and start Ollama
brew install ollama
ollama serve
ollama pull llama3.1:8b

Docker

docker compose up -d

Supported Bank Formats

Format	Banks	How
CSV	Chase, Bank of America, Wells Fargo, any bank	Download from bank website
PDF	Chase credit card statements	Download from Statements page
Image	Any bank screenshot	Screenshot your banking app

Tech Stack

Layer	Technology	Why
API	FastAPI	Async, auto-docs, 2x faster than Flask
ML Categorizer	LightGBM	3x faster than XGBoost, 94%+ accuracy
Forecaster	NeuralProphet	55-92% more accurate than Prophet
Anomaly Detection	PyOD (Isolation Forest)	Unsupervised, no labels needed
Risk Scoring	Weighted Ensemble	Fully explainable, 0-100 scale
AI Advisor	Ollama + ChromaDB (RAG)	Free, local, private
Frontend	Next.js + shadcn/ui + Recharts	Fast, beautiful, dark theme
Database	SQLite	Zero config, single file

API Endpoints

Endpoint	Method	Description
/api/transactions/upload	POST	Upload CSV/PDF/image
/api/transactions/generate-sample	POST	Generate demo data
/api/transactions/stored	GET	Get stored transactions
/api/transactions/clear	DELETE	Clear all data
/api/predictions	GET	Forecasts + risk + anomalies
/api/predictions/alerts	GET	Financial alerts
/api/predictions/summary	GET	Quick dashboard summary
/api/advisor/chat	POST	Chat with AI advisor
/api/advisor/index	POST	Re-index data for advisor
/api/advisor/status	GET	Advisor status
/health	GET	Health check

Project Structure

PredictWallet/
├── backend/
│   ├── app/
│   │   ├── api/            # FastAPI endpoints
│   │   ├── ml/             # ML models (categorizer, forecaster, anomaly, risk)
│   │   ├── services/       # Business logic (ingestion, alerts, RAG advisor)
│   │   └── core/           # Config, database, schemas
│   └── tests/              # 154 tests
├── frontend/
│   ├── src/app/            # Next.js pages
│   ├── src/components/     # React components
│   └── src/lib/            # API client, types, utilities
├── docs/
│   └── DECISIONS.md        # Why each tool was chosen
├── docker-compose.yml
├── Makefile
└── README.md

Running Tests

cd backend
python -m pytest tests/ --tb=short -q

Privacy

• 100% local — your financial data never leaves your device
• No external API calls (Ollama runs locally)
• No tracking, no analytics, no data collection
• SQLite database stored on your machine only

Author

Atharva Joshi — GitHub | LinkedIn

License

MIT