Skip to content

Latest commit

 

History

History
177 lines (142 loc) · 4.75 KB

README.md

File metadata and controls

177 lines (142 loc) · 4.75 KB

💰 Smart Finance Tracker

A modern, AI-powered expense tracking application built with Streamlit that helps you manage your personal finances through natural language input and intelligent categorization.

✨ Features

Core Features

  • 🤖 Natural Language Processing for expense/income entry
    • Intelligent parsing of casual inputs like "Spent $50 on groceries yesterday"
    • Automatic date detection from natural language
    • Smart categorization of transactions
  • 💬 Chat-like interface for easy data entry
  • 📈 Google Sheets integration for reliable data storage
  • 📱 Responsive design for both desktop and mobile

Transaction Management

  • 💸 Support for multiple transaction types:
    • Regular income and expenses
    • Pending payments (To Pay)
    • Pending receivables (To Receive)
  • 🏷️ Hierarchical categorization with categories and subcategories
  • 📝 Detailed transaction descriptions
  • 📅 Flexible date handling for both transaction and due dates

Analytics & Insights

  • 📊 Comprehensive financial analytics:
    • Overview dashboard with key metrics
    • Income analytics
    • Expense analytics
    • Pending transactions summary
  • 📈 Advanced visualizations:
    • Monthly income vs expenses trends
    • Category-wise breakdowns
    • Top income sources and expense categories
    • Weekly spending patterns
  • 💡 Smart insights:
    • Weekday vs weekend spending analysis
    • Fixed vs variable expense detection
    • Week-of-month spending patterns
  • 📅 Flexible date filtering:
    • All time view
    • Yearly analysis
    • Monthly analysis
    • Custom date ranges

🚀 Getting Started

Prerequisites

  1. Python Environment:

    • Python 3.8 or higher
    • pip package manager

  2. Google Cloud Setup:

    • Google account
    • Google Cloud project
    • Google Sheets API enabled
    • Service account with appropriate permissions

  3. Gemini AI API:

    • Gemini AI API key (for natural language processing)

Detailed Setup Process

  1. Clone the Repository:

    git clone https://github.com/Spritan/expense_tracker
cd expense_tracker

  2. Install Dependencies:

    pip install uv
uv sync

  3. Google Cloud Platform Setup: a. Create a new project in Google Cloud Console b. Enable the Google Sheets API:

    • Go to APIs & Services > Library
    • Search for "Google Sheets API"
    • Click Enable c. Create a service account:
    • Go to APIs & Services > Credentials
    • Click "Create Credentials" > "Service Account"
    • Fill in the service account details
    • Create and download the JSON key file d. Set up Google Sheet:
    • Create a new Google Sheet
    • Share it with the service account email
    • Note down the Sheet ID from the URL

  4. Environment Configuration: Create a .env file in the project root with:

    GOOGLE_SHEETS_CREDENTIALS=path/to/your/credentials.json
GOOGLE_SHEET_ID=your_google_sheet_id
GEMINI_API_KEY=your_gemini_api_key

  5. Initialize Google Sheet: The application will automatically set up the required columns:

    • Date
    • Amount
    • Type (Income/Expense/To Pay/To Receive)
    • Category
    • Subcategory
    • Description
    • Due Date (for pending transactions)

Running the Application

  1. Start the Application:

    uv run streamlit run Home.py

  2. First-Time Setup:

    • The application will automatically verify and initialize the Google Sheet structure
    • You'll see a success message if everything is configured correctly

  3. Verify Installation:

    • Check if the chat interface appears
    • Try adding a sample transaction
    • Verify if the analytics tabs are working

🔧 Configuration

Transaction Categories

Income Categories:

  • Salary
  • Investments
  • Business
  • Other Income

Expense Categories:

  • Food & Dining
  • Shopping
  • Transportation
  • Bills & Utilities
  • Entertainment
  • Health & Wellness
  • Other Expenses

Pending Transaction Types

  • To Pay (for upcoming payments)
  • To Receive (for expected income)

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Built with Streamlit
  • Powered by Google's Gemini AI
  • Uses Google Sheets API for data storage
  • Visualizations powered by Plotly

💡 Support

For support:

  1. Check the documentation above
  2. Open an issue in the GitHub repository
  3. Contact the maintainers

🔒 Security Note

  • Never commit your .env file or credentials to version control
  • Keep your API keys and credentials secure
  • Regularly rotate your service account keys
  • Follow the principle of least privilege when setting up service accounts