README.md

---
title: Money Manager
emoji: 💸
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
---

# 💸 Personal Finance Manager

A Gradio-based web application for managing personal finances with LLM-powered natural language expense logging. Log expenses like "Spent $15 on a burrito at Chipotle" and let AI parse them into organized ledger entries.

## Features

✨ **Natural Language Parsing**: Describe expenses in your own words—the LLM handles extraction
📊 **Dynamic Ledger**: Real-time table showing all expenses with sorting and filtering
💰 **Total Tracking**: Automatically calculated total spending that updates instantly
🏷️ **Smart Categorization**: Expenses are automatically categorized (Food, Transportation, Utilities, etc.)
🎨 **Clean Dashboard**: Financial-themed UI using Gradio's Soft theme
🔄 **Session Persistence**: Ledger data persists throughout your session
⚡ **Fallback Parser**: Works even without LLM API keys using rule-based parsing

## Tech Stack

- **Frontend**: Gradio (Python web framework)
- **Data**: Pandas (DataFrames)
- **LLM**: LangChain with HuggingFace Hub or OpenAI
- **Language**: Python 3.8+

## Setup

### 1. Clone the Repository
```bash
cd financemanager
```

### 2. Create Virtual Environment
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 3. Install Dependencies
```bash
pip install -r requirements.txt
```

### 4. Configure API Keys (Optional)

Copy `.env.example` to `.env` and add your API keys:

```bash
cp .env.example .env
```

Edit `.env`:
- **HuggingFace**: Get token from https://huggingface.co/settings/tokens
- **OpenAI**: Get key from https://platform.openai.com/api-keys

If you don't configure any API keys, the app will use the fallback rule-based parser.

### 5. Run the Application

```bash
python app.py
```

The app will launch at `http://localhost:7860`

## Usage

1. **Describe Your Expense**: Type a natural language description in the input box
   - Examples:
     - "Spent $15 on a burrito at Chipotle"
     - "Paid $1200 for rent today"
     - "Gas: $45.50"
     - "Movie tickets $32"

2. **Click Log Expense** or press Enter
3. **View Results**: 
   - Status message confirms the entry
   - Table updates with the new expense
   - Total spending updates automatically
   - Expenses sorted by date (newest first)

## How It Works

### LLM-Based Parsing (Recommended)
When an LLM is configured, the app sends your input to the model with this prompt:

```
Parse this expense and return JSON with:
- date (YYYY-MM-DD)
- description (what was purchased)
- category (Food, Transportation, Utilities, etc.)
- amount (numeric value)
```

The LLM returns structured JSON that the app parses and stores.

### Fallback Parser
Without an LLM, the app uses:
- **Regex** to extract dollar amounts
- **Keyword matching** for category detection
- **Current date** for entries without explicit dates

## Expense Data Structure

Each entry contains:

| Field | Example | Notes |
|-------|---------|-------|
| Date | 2024-05-01 | YYYY-MM-DD format |
| Description | Burrito at Chipotle | What was purchased |
| Category | Food | Auto-categorized |
| Amount | 15.00 | Dollar amount |

## Supported Categories

- **Food**: Restaurant, groceries, coffee
- **Transportation**: Gas, Uber, parking, taxi
- **Utilities**: Electric, water, internet, phone
- **Entertainment**: Movies, concerts, books, games
- **Rent**: Rent, mortgage, apartment
- **Other**: Uncategorized expenses

## Deployment to HuggingFace Spaces

### 1. Create a Space
- Go to https://huggingface.co/spaces
- Click "Create new Space"
- Choose "Gradio" as the SDK
- Set repository visibility to public/private

### 2. Upload Files
```bash
git clone https://huggingface.co/spaces/your-username/your-space
cd your-space
# Copy app.py, requirements.txt, .env to this directory
git add .
git commit -m "Add finance manager"
git push
```

### 3. Add Secrets
In your Space's Settings → Repository secrets, add:
- `HUGGINGFACEHUB_API_TOKEN`
- `OPENAI_API_KEY` (if using OpenAI)

The space will auto-deploy and be accessible at: `https://huggingface.co/spaces/your-username/your-space`

## Customization

### Change Theme
In `app.py`, line 214:
```python
with gr.Blocks(theme=gr.themes.Soft()) as demo:
```

Try: `Default()`, `Glass()`, `Monochrome()`, `Soft()`, `Base()`

### Add More Categories
Edit `parse_expense_fallback()` function, around line 149:
```python
categories = {
    "Shopping": ["amazon", "mall", "store", "buy"],
    "Medical": ["doctor", "pharmacy", "clinic"],
    # Add more...
}
```

### Change LLM Model
In `initialize_llm()`, line 68:
```python
repo_id="mistralai/Mistral-7B-Instruct-v0.2",
# Try: "HuggingFaceH4/zephyr-7b-beta", "meta-llama/Llama-2-7b-chat-hf"
```

## Limitations

- ⚠️ Session data is not persisted between app restarts (no database)
- ⚠️ All amounts are in USD (no multi-currency support)
- ⚠️ LLM parsing may fail for very ambiguous inputs
- ⚠️ No built-in authentication (use for personal/private deployments)

## Future Enhancements

- [ ] CSV export functionality
- [ ] Monthly/yearly summaries with charts
- [ ] Budget alerts
- [ ] Receipt image upload
- [ ] Multi-currency support
- [ ] SQLite database for persistence
- [ ] User authentication for Spaces deployment

## Troubleshooting

### "LLM not available" Warning
The app works without an LLM. This just means it's using the fallback parser. Add an API key to `.env` to enable intelligent parsing.

### "JSON parsing error"
The LLM response format was unexpected. Try rephrasing your expense description or check your API key.

### App Hangs on Startup
- Check that your API keys are correct
- Ensure you have internet connectivity
- Try disabling the LLM by not setting environment variables

## License

MIT License - feel free to modify and deploy!

## Support

For issues or suggestions, please check the code comments or modify as needed.

---

**Happy budgeting! 💰**