Budgeting Bot Bubsy

A personal finance budget-managing tool deployed as a chatbot on the messaging platform Telegram. Bubsy records your expenses, shows your spending and keeps track of your budget.

Table of Contents

1. About
2. Getting Started
   • Pre-requisites
   • Setting up the Database
   • Creating the Telegram Bot
   • Configuration
3. Usage
   • Starting the bot
   • Conversing with the bot
4. Deployment
5. Future Improvements

Getting Started

Pre-Requisites

To run the application you will need the following:

• Python 3.9+
• SQL Relational Database

To install the required Python packages:

pip3 install -r requirements.txt

Note: To communicate with the bot via the messaging platform Telegram you need Telegram account and application.

Setting up the Database

The application requires an SQL relational database to work. To set up your database you may use the scripts provided in db/ directory.

• db/createtables.sql creates the required tables in the database
• db/importdata.sql, db/categories.csv, db/budget.csv, db/spending.csv can be used to prefill the database with some data if you wish.

Creating the Telegram Bot

(Optional) To converse with the bot through the messaging platform Telegram, you will need to create the bot using the application. You may find the instructions on how to do this here. Once you have your bot token you can proceed with the configuration as shown below.

Configuration

The application contains three configuration files you must fill in before running the bot:

• src/db_config.json
  The configuration settings for the database.

  {
  "dbHost": "localhost",
  "dbName": "budget",
  "dbUser": "bubsy",
  "dbPassword": "password"
  }

• src/telegram_config.json
  (Optionally) The configuration settings for the Telegram bot.

  {
    "token": "token",
    "privateBot": true,
    "chatId": 0
  }

  To obtain the chatId and secure your bot, you may run the application with the flags as follows:
  python3 app.py --telegram --identify-users
  This will echo the chatId of all incoming messages to the bot with the given token.

• src/ocr_config.json
  (Optionally) The configuration settings for the OCRSpace API used for receipt scanning. You can register and acquire the API key here.

  {
    "apiKey": ""
  }

Usage

Starting the bot

You may run the application by:

• python3 app.py --terminal to converse with the bot in the terminal, or alternatively,
  
• python3 app.py --telegram (default) to use the messaging platform Telegram

Conversing with the bot

Some of the features that Bubsy currently supports include:

• recording an expense
• showing your budget
• showing your spending in a specified time frame
• changing your budget
• warning you when your spending is close or above your budget limits
• (NEW) scanning photos of receipts to find the total amount spend

Try sending these messages:

• I spent £5 on groceries yesterday or
• Show me my budget or
• How much did I spend last weekend?

Deployment

The application has been deployed on an EC2 AWS instance.

Future Improvements

Some of the features I plan to add to the project:

• Support for keeping track of recurring payments
• Showing a spending graph via Google Sheets API

To see an up-to-date list of features I am currently working on, see the issues section of the repository.