Ayumi - Chat-GPT powered telegram bot

• Author: satojkee
• Project: ayumi-bot
• Production: AyumiBot

Production version is secured and won't allow you to use AI features without authorization.

---

Features

• Text generation ✔️
• Image generation ✔️
• Speech-to-text ✔️
• Inline mode support ✔️
• Private chat support ✔️
• Access management system with different levels of access ✔️
• Group chat support ✔️
• Deepseek support coming soon

Useful links

• OpenAI API docs
• pyTelegramBotAPI
• SQLAlchemy
• BotFather
• GetIDsBot
• PyBabel
• PostgreSQL

Usage guide

Clone repository

git clone https://github.com/satojkee/ayumi-bot.git

Install dependencies

pip3 install -r requirements.txt

Configure environment variables

Set each property using .env file or via cli

Required variables

Variable	Description	Hint
DATABASE_URI	Database credentials	PostgreSQL + asyncpg, format: postgresql+asyncpg://{POSTGRES_USER}:{POSTGRES_PASSWORD}@{POSTGRES_HOST}:{POSTGRES_PORT}/{POSTGRES_DB}
TELEGRAM_TOKEN	Telegram bot token	visit BotFather and create your own bot
TELEGRAM_OWNER_ID	Telegram admin id	use GetIDsBot to get your account id
TELEGRAM_BOT_NAME	Telegram bot name	this name is used as filter for prompts, e.g: TELEGRAM_BOT_NAME, hello! or TELEGRAM_BOT_NAME@i, image of a cute kitten.
OPENAI_PROJECT_ID	OpenAI project ID	visit OpenAI and create a new project
OPENAI_SECRET_KEY	OpenAI API token	create a new API-KEY for a created project on OpenAI platform

Additional variables

Used in docker-compose case, don't forget to build a DATABASE_URI in proper way
Example: postgresql+asyncpg://postgres:postgres_secret@postgres:5432/test_database

Variable	Description	Hint
POSTGRES_USER	Database user	postgres for example
POSTGRES_PASSWORD	Database password	postgres_secret for example
POSTGRES_DB	Database name	test_database for example

Edit app_config.toml if needed (optional)

For example, you can replace the gpt-4o-mini text-model with gpt-3.5-turbo or gpt-4o, but don't forget to enable this model in your project settings on OpenAI platform

Explanation

• security

  • levels - a list of supported security levels in ascending order
  • zero - this value is used in keyboard.access_keyboard and handlers.admin.access_callback to represent negative access response

• security.ai - currently supports level and allow_groups params

  • textgen - text generation
  • textgen_inline - text generation in inline mode
  • speech_to_text - speech-to-text
  • imagegen - image generation

• inline.query

  • min_len - min length of a prompt in inline mode

• locale

  • languages - a list of supported languages

• logger

  • level - logger level, supported levels:
    • DEBUG - default
    • INFO
    • WARNING
    • ERROR
    • CRITICAL

• openai

  • directive - Answers the question: "How to act?", for textgen and textgen_inline

• locale.translator - supports all gettext.translation function params

• openai.text - supports all openai.client.chat.completion.create function params

• openai.image - supports all openai.client.images.generate function params

• openai.speech_to_text - supports all openai.client.audio.transcriptions.create function params

• sqlalchemy - supports all SQLAlchemy.create_async_engine function params

[security]
levels = [1, 2, 3]
zero = 0

[security.ai.textgen]
level = 1
allow_groups = true

[security.ai.textgen_inline]
level = 1
allow_groups = false

[security.ai.speech_to_text]
level = 2
allow_groups = true

[security.ai.imagegen]
level = 3
allow_groups = false

[sqlalchemy]
pool_pre_ping = false
echo = false

[locale]
languages = ["en", "uk"]

[locale.translator]
domain = "messages"
localedir = "locale"

[logger]
level = "DEBUG"

[openai]
directive = "Your name is Ayumi. You are a helpful telegram chat assistant. Act like a human. Respond in language you are asked."

[openai.text]
model = "gpt-4o-mini"

[openai.image]
size = "1024x1024"
model = "dall-e-3"

[openai.speech_to_text]
response_format = "text"
model = "whisper-1"

[inline.query]
min_len = 3

See available cli commands

python main.py --help

Recreate database schemas

Current version of Ayumi supports only async version of SQLAlchemy (tested only with PostgreSQL database and asyncpg driver).

python main.py --reinit

Compile locales PyBabel guide

pybabel compile -d locale

Start bot

python main.py

---

Docker guide

With remote PostgreSQL database

Don't forget to set required variables in Dockerfile or directly in docker run --env ...

Build the image

docker build -t ayumi .

Create and start a container

docker run --env ... ayumi

Docker compose PostgreSQL + AyumiBot

Create .env file in the project root and configure all required + additional variables.

Build images and start containers

The ayumi_bot container may restart several times, due to the long postgres container init

docker-compose up -d

---

Telegram bot configuration via BotFather

How to highlight commands?

Got to @BOT_NAME > Edit Bot > Edit Commands and send the following message

start - Let's start <3
help - Usage guide
get_access - Ask for access to my AI features
users - The list of authorized users (admin only)
groups - The list of authorized groups (admin only)

How to configure inline mode?

Go to @BOT_NAME > Bot Settings > Inline Mode turn it on and set the placeholder

Example:

Ask me anything

---

Pybabel guide

Extract keys

This command extracts all keys (values inside each gettext function) from sources

pybabel extract . -o locale/base.pot

Init new locale

pybabel init -l de -i locale/base.pot -d locale

Once your new locale is created, you can edit it in locale/de/LC_MESSAGES/messages.po

Update .po files

This command execution is required every time you rename old or add new keys

pybabel update -i locale/base.pot -d locale

Compile locales

Once you have finished editing your locale, you must compile it (otherwise, you'll see keys instead of actual translations)

pybabel compile -d locale