This repository is now archived, use at your own risk (update dependencies first, if you ever use this)

Pictobot

A chatbot to use as a basic universal translator. If you can't say it, show it!

This bot is shown here as an example of a telegram bot written in python, which might be helpful to some. It is not a framework or a template, in my opinion. But it was enough IMHO to participate in the Telegram BotPrize, because I believe in the usefulness of this simple idea. The contest was a good opportunity to learn about chatbots and pictograms.

• Getting Started
  • Prerequisites
  • Installing
• Running the bot
• Running the tests
• Deployment
• Built With
• Docs
• Contributing
• Author
• License
• Acknowledgments

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for pointers on how to deploy the project on a live system.

Prerequisites

If you want to follow these instructions to run the chatbot on your machine, you need:

• python 3.6 or higher.
• a bot TOKEN from Telegram. You should also toggle inline mode for your bot (/setinline command within BotFather). I recommend creating two bots if you want to get serious: one for dev/test and the other one for production.
• If you wish to run the integration tests, you'll also need to get API keys from Telegram: follow instructions here.

These instructions are for running in dev/test mode on MacOS and Linux.

Copy this project's files where you want them:

$ cd /to/where/you/want/the/bot/to/live
$ git clone https://github.com/baychimo/pictobot

If you don't have git installed, you can download the files by clicking the green "Clone or download" button at the top of the page.

Installing

Create a virtual environment on your machine with:

$ python3 -m venv .virtualenvs/pictobot

Activate the environment and install the needed python packages:

$ source ~/.virtualenvs/pictobot/bin/activate && cd /to/where/you/want/the/bot/to/live
(pictobot)$ pip install --upgrade pip setuptools
(pictobot)$ pip install -r requirements.txt

Replace the fake TOKEN in the file settings/local_sample.py by yours and rename that file to local.py. If you wish to run the integration tests, also replace the values of api_id and api_hash with yours.

Running the bot

If you followed the above instructions, to run the bot locally you just need to:

(pictobot)$ python pictobot/core.py

Now go to your telegram app (on your smartphone/desktop/browser) and contact your bot by its name (the one you chose earlier): @YourBot.

Running the tests

If you wish to run the automated tests for this project, just run these commands from the root of the project.

For unit tests:

(pictobot)$ pytest -v --durations=0 --hypothesis-show-statistics tests/test_unit.py

For integration tests:

(pictobot)$ pytest -v --durations=0 --hypothesis-show-statistics tests/test_integration.py

The integration tests require patience. They are done through a userbot, and to avoid being (rightfully) blacklisted or rate-limited by Telegram, there is a 3 second wait between each test.

Deployment

If you want to run it on a server, I can write instructions. You just need to ask. For now, if you already have python experience, you should read the last lines of core.py and check the settings in settings/production_sample.py to get you started. I used nginx/uwsgi/letsencrypt/supervisor, but other combos are possible (check out python-telegram-bot docs on the subject). If you are in a hurry, start by the great wiki of the Python Telegram Bot framework.

Built With

• Python-Telegram-Bot - The excellent Telegram Bot framework, making it very easy to get started with Telegram. Their docs are good and they are very helpful on their Telegram group too. Highly recommended!
• FuzzyWuzzy - "Fuzzy string matching like a boss". That says it all.
• The Noun Project - All the images used by the bot were downloaded from the noun project website before being adapted into pictograms with inkscape, the credits are listed below.

Docs

The docstring generated docs are in the gh-pages branch. They are published here: baychimo.github.io/pictobot

Contributing

I don't intend to maintain this project unless I have some new ideas that would make the process fun. But if you have any questions, need further instructions for your platform, feel free to open an issue. And feel free to fork it of course! That's why I put it here for.

Here are some ideas for improvments:

• Store data in a DB instead of dicts. To make things practical this should be accompanied by some UI to update the database and add images: a micro webapp?
• The bot is translatable, and translated in french for now. But there needs to be a way for users to switch languages which means storing at least minimal user data somewhere.
• Find a way to automate the creation and tagging of pictograms. Maybe a toolchain involving a GAN and imagemagick?

Have fun!

Author

Jonathan Guitton - Baychimo.

License

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

Acknowledgments

• Inspiration
  • Star Trek's universal translator: we have to start somewhere, right?
  • My own experience as a travelling introvert. Most people don't want to mimic/gesticulate that they need toilet paper. Or so I thought :-)
• Beautiful logo made by the great Sebastien Lasserre.
• All images used by the pictobot are licensed under Public Domain, except for the following which are licensed under Creative Commons / Attribution 3.0 United States CC BY 3.0 US:
  • By Arthur Shlain:
    • Shopping Cart | Retrieved on 2016-07-13.
    • Toilet Paper | Retrieved on 2016-07-13.
    • Band Aid | Retrieved on 2016-07-13.
    • Toilet | Retrieved on 2016-07-13.
    • Wrench | Retrieved on 2016-07-13.
  • By Mikhail Iskandarov: Toilet Paper | Retrieved on 2016-07-13.
  • By Vicons Design:
    • ATM Withdrawal | Retrieved on 2016-07-13.
    • Bank | Retrieved on 2016-07-13.
  • By Greg Beck: Health Foods | Retrieved on 2016-07-13.
  • By Martin Lebreton: Grocery Basket | Retrieved on 2016-07-13.
  • By MD Delwar Hossain:
    • Hammer | Retrieved on 2016-07-16.
    • Hammer | Retrieved on 2016-07-16.
    • Screwdriver | Retrieved on 2016-07-16.
  • By Ricardo Moreira: Tools | Retrieved on 2016-07-16.
  • By useiconic.com:
    • Screwdriver | Retrieved on 2016-07-16.
    • Pencil | Retrieved on 2016-07-16.
  • By Stanislav Levin: Umbrella | Retrieved on 2016-07-23.
  • By Edward Boatman: Umbrella | Retrieved on 2016-07-23.
  • By Eric Milet: Photographer | Retrieved on 2016-07-23.
  • By Eva Verbeek: Charger | Retrieved on 2016-07-23.
  • By Anbileru Adaleru: Charger | Retrieved on 2016-07-23.
  • By Gregor Črešnar: Charger | Retrieved on 2016-07-23.
  • By Clair Jones: Adapter | Retrieved on 2016-07-23.
  • By Ed Harrison: Bunk Beds | Retrieved on 2016-07-23.
  • By Krisada: Museum | Retrieved on 2016-07-23.
  • By Jakob Vogel: Parachute | Retrieved on 2016-07-23.
  • By Juan Pablo Bravo: Skydiving | Retrieved on 2016-07-23.
  • By Creative Stall: Waiter | Retrieved on 2016-07-23.
  • By Pieter J. Smits: Lake | Retrieved on 2016-07-23.
  • By Icon Island: Sunglasses | Retrieved on 2016-07-24.