Tellama

Tellama is a lightweight bot that integrates LLMs with Telegram's bot API. It allows you to chat with your favorite language model in Telegram private or group chats.

[!IMPORTANT] Tellama is still in early stages of development. The current version is finished in just two afternoons. You may run into bugs, unexpected behavior, or incomplete documentation. Please report any problems you encounter by opening an issue.

Here is a demo of Tellama in action:

Quick Start

Option 1: Run with Docker

The official image is hosted at ghcr.io/k4yt3x/tellama:latest.

To pass options with environment variables:

docker run \
  --network=host \
  -v $PWD:/data \
  -e TELEGRAM_TOKEN="YOUR_TELEGRAM_BOT_TOKEN" \
  -e OLLAMA_MODEL="YourModelName" \
  ghcr.io/k4yt3x/tellama:latest

You can also save the environment variables in a .env file to make things easier:

docker run \
  --network=host \
  -v $PWD:/data \
  --env-file .env \
  ghcr.io/k4yt3x/tellama:latest

To pass options with command-line arguments:

docker run \
  --network=host \
  -v $PWD:/data \
  ghcr.io/k4yt3x/tellama:latest \
  --telegram-token="YOUR_TELEGRAM_BOT_TOKEN" \
  --model="YourModelName"

Option 2: Install from PyPI

You can also install Tellama directly using pip:

pip install tellama

To pass options with environment variables:

export TELEGRAM_TOKEN="YOUR_TELEGRAM_BOT_TOKEN"
export OLLAMA_MODEL="YourModelName"

tellama

You can also save the environment variables in a .env file to make things easier:

set -a; source .env; set +a
tellama

To pass options with command-line arguments:

tellama --telegram-token="YOUR_TELEGRAM_BOT_TOKEN" --model="YourModelName"

Further Configuration

To see all available options, run:

tellama --help

or consult the project repository for more details.

Configuration

You will need to add custom default instructions for the model. Run the bot once to create the database, then add the instructions to the chat_instructions table in the SQLite database. A custom instruction entry with the chat_id of NULL will be used as the default instruction for all chats. You can also add instructions for specific chats by adding entries with the chat_id of the chat you want to customize.

INSERT INTO chat_instructions (instructions) VALUES ('Your custom instructions');

Here is an example for how the instructions should look like:

<instructions>
- Your name is Tellama.
- You are an AI chatbot built by @JohnDoe for Telegram group chats.
- You should not engage in any harmful, illegal, or unethical conversations.
- You should be polite, respectful, and helpful to all users.
- You should obey laws, morals, and ethics.
- Contents between `<instructions></instructions>` are instructions for you to follow.
- Contents after `<instructions></instructions>` are messages from users in the chat.
- User messages are in the format of `<nickname>: <message>`.
- Your responses should be text-only, without any tags or identifiers.
</instructions>

License

Tellama is licensed under GNU AGPL version 3.