Expense Insights Dashboard Backend

Intelligent Document Processing — Extract, normalize, and categorize financial transactions from bank statements, receipts, and invoices (PDFs, images, etc.) using ML (PyTorch/Transformers) with GenAI (Gemini) fallback.

Project Structure

├── AGENTS.md                  # AI agent context
├── README.md
├── requirements.txt
├── .env                       # API_KEY for Gemini
├── data/
│   ├── headernames.csv        # Training data — header column classifier
│   └── transactions.csv       # Training data — transaction classifier
├── headers_classifier/        # Saved header classification model
├── transactions_classifier/   # Saved transaction classification model
├── training/
│   ├── train_headers_classifier.py
│   └── train_transactions_classifier.py
└── src/
    ├── main.py                # FastAPI entry point
    ├── utils.py               # LLM, unstructured, column normalization
    ├── predict.py             # ML model inference (headers + transactions)
    ├── db/
    │   └── mongodb.py         # MongoDB connection
    └── routes/
        └── upload.py          # POST /upload/ endpoint

Setup Instructions

1. Clone and enter the repository:

   git clone <repo-url>
   cd expense-insights-backend
   

2. Create virtual environment & environment variables:

   python -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   export API_KEY="<gemini-api-key>"  # Gemini API key for LLM fallback
   

3. Install the required dependencies:

   pip install -r requirements.txt
   

4. Train ML Models:

   python training/train_headers_classifier.py
   python training/train_transactions_classifier.py
   

5. Set up MongoDB:

   • Ensure MongoDB is installed and running on localhost:27017
   • Update connection settings in src/db/mongodb.py if needed

6. Run the application:

   fastapi dev src/main.py
   

Usage

Send a POST request to /upload/ with a PDF (or other document format) containing transaction data. The application processes the file and returns categorized transactions as JSON.

How the Pipeline Works

1. PDF → tabula-py extracts tables
2. ML header classifier normalizes column names → date, description, amount, or ignore
3. ML transaction classifier categorizes each row (e.g. Transport, Groceries, Food & Drinks)
4. Fallback: If ML extraction fails → unstructured.io extracts text → Gemini LLM extracts CSV
5. Post-processing: Currency symbols removed, amounts parsed, dates normalized

Dependencies

• FastAPI
• PyTorch / HuggingFace Transformers
• MongoDB (pymongo)
• Pandas
• Tabula-py
• Unstructured.io
• scikit-learn
• Google Gemini API