README.md

metadata

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

cd financemanager

2. Create Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure API Keys (Optional)

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

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

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

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:

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:

categories = {
    "Shopping": ["amazon", "mall", "store", "buy"],
    "Medical": ["doctor", "pharmacy", "clinic"],
    # Add more...
}

Change LLM Model

In initialize_llm(), line 68:

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! 💰