Sample Assistant Bot (a.k.a. Aski)

Summary

• Introduction
• Purpose
• Before you start the bot
• Starting the bot
• Commands
• Setup
• Known issues
• Ongoing implementations
• Future implementations

Introduction

This project (@sampleassistantbot) started as a personal project to experiment and test the several functionalities offered by the python-telegram-bot wrapper.
After thinking about the functionalities I wanted to develop for myself, I thought that it'd have been fun to develop something that many users could use.
So, I started to develop a general purpose bot, to assist the users during their daily tasks, just like a virtual assistant, but without the support of kind of AI.

That's it.

Purpose

The purpose of the bot is to provide the user a set of functionalities that it can use to get informed on the local news, or to create a todo, or to get weather information.

The user can interact accomplish these actions thanks to a set of commands, like:

• /help, to guide the user using the bot
• /news, to read the latest local news (based on user's location)
• /setlocation, to let the user set (and save) its location to the database
• /todo, to create a todo (with optional reminder)
• /todos, to list, check or remove user's todos
• /weather, to show the current weather (based on user's location)

Before you start the bot

If you read the Purpose section of this document, you've probably noticed that for some commands, their use is dependant on the user's location.
That's because the bot can't give the user information about the local news or about the weather if it doesn't know where the user is located.
Additionally, to let users from all around the world use this bot, I had to take care about different time zones, always based on the user's location.
Therefore, before you start, you need to know that the bot will save the location you'll share with it.
That means that, for testing purposes, you don't have to use your actual location, but you can set any nearby location, so you don't have to deal with different time zones if you want to test the /todo command features, or have a complete different results when using the /weather command.

Please note: the bot is currently offline, since I still didn't deploy it somewhere.

Starting the bot

Once you start the bot, you'll see:

Commands

/help

With this command, the user can get help on the various features that the bot provides.
By typing /help <command>, the user receives a specific guide on how to use the command provided.

/news

With this command, the user receives a set of local news based on the user's location.
Please note: without setting a location, this command is unable to provide the expected result.

/setlocation

With this command, the user can save and update its location.
Please note: if you try to share your location from Telegram Desktop, you'll see a message like the rightmost one:

/todo

With this command, the user can create a todo with an optional reminder. A todo has different attributes, like:

• details, or todo's body
• due date, or todo's completion date
• remind at, or todo's reminder (optional)

Please note: without setting a location, this command is unable to provide the expected result.

The user can optionally set a reminder:

Once the to-do reminder is triggered, the user can react with an emoji to the message to mark it as completed:

If the to-do is created without a reminder, the user will be reminded just at the to-do due date/time:

/todos

With this command, the user can manage the list of its todos.

/weather

With this command, the user receives weather information based on its location.
Please note that without setting a location, this command is unable to provide the expected result.

Setup

In this section, you can find the step-by-step guide on how to run this project on your local machine.

First thing first, clone the repository locally with the command

git clone https://github.com/FrancescoDiMuro/sample-assistant-bot.git

Then, you can proceed in two ways:

1. using Docker Compose
2. using the virtual environment

Using Docker Compose

Be sure to have Docker Compose installed on your PC.
Then, once you changed directory to the projet root, all you need to do is execute the command

docker compose --env-file ./app/.env up --detach

and you're pretty much done.

If you want to remove the app from Docker, together with the app image and the created volume, use the command

docker compose down --rmi local --volumes

Using the Virtual Environment

If you don't want or you can't use the Docker Compose solution, you might want to use this one.

First thing first, be sure to have installed Python on your PC.
This application has been developed with Python 3.12.7, but every version equal or above 3.10 should work fine.

If you want to be sure that you've installed Python correctly, or you want to check if you already have it installed on your PC, use the command

python --version

or

py --version

Once you managed to install/verify that Python is installed on your PC, you need to create a virtual environment.

Move to the project root, and run the command

python -m venv ./.venv

or, if you have already the virtualenv package installed

python -m virtualenv ./.venv

Once the command finishes its execution, you have to activate the venv, using the command

./.venv/Scripts/activate

You can verify that the venv has been correctly activated by checking the prefix (.venv) before the path in the terminal.

Moving on, you need to install the required packages, executing the command

pip install -r ./app/requirements.txt

Once the command finishes its execution, you completed the application setup, and it's time to setup the database.

This step depends mainly on your preferences, but if you want to make it simple, you can use a local SQLite database.

All you need to do is to be sure that you're using the SQLite values for the environment variables in the .env file for the SQLAlchemy section (default).

In case you want to use another database, you can set it up and update the environment variables accordingly (following the official SQLAlchemy documentation).

Once you've completed this step, use the command

python app

to start the bot.

Known issues

Use of synchronous connections with the database

At the moment, the bot doesn't use an async connections to the database through the SQLAlchemy ORM, so there might be issues related to this implementation.

Ongoing implementations

• Create a todo with a message

Future implementations

• Async connections with the database
• Add integration tests
• Encrypt user data
• Let the user delete its data from the database
• Let the user set its location from Telegram Desktop

Go to summary