Laksh (Financial Agent)

A personal finance application to help you track and categorize your spending from various credit card statements with budget tracking and visualizations.

🚀 Features

• AI-Powered CSV Processing: Upload statements from any bank—Laksh auto-detects columns and formats, so you never have to wrangle CSVs again.
• LLM Transaction Categorization: OpenAI GPT-4o-mini powers dynamic, context-aware categorization with confidence scores and reasoning.
• LLM Budget Analysis: Get actionable, personalized budget recommendations and insights based on your real spending patterns.
• Universal Bank Support: AmEx, Chase, Citi, and more!
• Budget Tracking: Set monthly budgets for each category and track your progress visually.
• Neat Visualization: Charts, color-coded progress, interactive filtering, and critical numbers first make your finances easy to scan.
• Persistent Local Storage: All data is stored locally in SQLite, with full AI metadata.

🛠️ Tech Stack

• Frontend: Streamlit
• Backend: Python
• Data Storage: SQLite
• Visualization: Plotly
• Data Processing: Pandas
• AI/ML: OpenAI GPT-4o-mini, Custom LLM Processors

⚡️ Setup & Installation

1. Clone the repo:

   git clone https://github.com/sverma25/laksh
   cd laksh

2. Create and activate your Conda environment:

   conda create -n laksh python=3.12 -y
   conda activate laksh

3. Install dependencies:

   pip install -r requirements.txt

4. Set up your OpenAI API key (for LLM features):

   • Get your API key from OpenAI Platform
   • Recommended: Create a .env file in your project root:

     OPENAI_API_KEY=sk-your-api-key-here
     

5. Test your setup:

   python tests/test_llm_features.py

▶️ How to Run

Fire up the app with:

conda activate laksh
streamlit run app.py

Laksh will launch in your default browser. If your API key is set, LLM features are enabled automatically.

📋 How to Use

Spend Overview

• See your total spend, budget, and remaining amount at a glance.
• Each category is displayed in a card with spend, budget, and percentage.
• Charts show budget vs spend, color-coded for clarity.

Transaction Details

• Upload any CSV statement—Laksh auto-detects columns and processes your data.
• Transactions are categorized by AI, with confidence scores and reasoning.
• Filter by category, card, date, or search term.
• Download filtered data as CSV.

🎯 Budget Configuration

Budgets are set in config/categories.json. Each category has a budget field and subcategories:

{
    "Food": {
        "budget": 800,
        "subcategories": [
            "Groceries/Household",
            "Takeout",
            "Dine out",
            "Coffee"
        ]
    }
}

Tweak these budgets to match your goals and lifestyle.

AI Insights

• Get budget recommendations and spending insights powered by LLM.
• Discover patterns, anomalies, and receive actionable advice.
• See detailed AI reasoning for each categorization.

🤖 LLM Features & Configuration

Laksh uses OpenAI's GPT models for next-level transaction categorization and budget analysis:

• Dynamic Understanding: LLM analyzes merchant names, context, and transaction details to categorize with confidence and reasoning.
• Context Awareness: Considers amounts, original categories, and MCC codes.
• Fallback Safety: If LLM isn't available, Laksh falls back to keyword-based categorization.

Troubleshooting

• LLM processor not available: Check your API key and internet connection
• Failed to parse AI analysis response: Usually a temporary API issue—try again
• High API costs: Reduce batch size or use keyword-based categorization

Security Notes

• Never commit your API key to version control
• Transaction data is sent to OpenAI for processing
• All processed data is stored locally in SQLite

📸 Screenshots

(Screenshots coming soon!)

🛣️ Future Roadmap

• Enhanced AI Categorization: Even more detailed categorization
• Manual Re-categorization: Add the ability to manually edit transaction categories and train the AI from corrections.
• PDF Statement Support: Develop parsers for PDF credit card statements.
• Historical Trends: Add time-series analysis and spending trend visualization.
• Goal Setting: Allow users to set and track financial goals beyond monthly budgets.
• Export Features: Add support for exporting data to other financial applications.
• Custom Categories: Create temporary categories for limimted transactions (eg. spend on food while you travel vs general dine out)
• Connecting financial accounts: Connect your external accounts (checking/savings/investment) to get a full picture of your finances and wealth