# TeLLMgramBot
The basic goal of this project is to create a bridge between a Telegram Bot and a Large Language Model (LLM), supporting both OpenAI's GPT models and Anthropic's Claude models.
* To use this library, you must have a Telegram account **with a user name**, not just a phone number. If you don't have one, [create one online](https://telegram.org/).
* If added to a Telegram group, the bot must be [administrator](https://www.alphr.com/add-admin-telegram/) in order to respond to a user calling out its name, initials, or nickname.
<img src="assets/TeLLMgramBot_Logo.png" width=200 align=center />

## Telegram Bot + LLM Encapsulation
* The Telegram interface handles special commands, especially on some basic "chatty" prompts and responses that don't require LLM, like "Hello".
* The more dynamic conversation gets handed off to the LLM to manage prompts and responses, and Telegram acts as the interaction broker.
* Pass the URL in [square brackets] and mention how the bot should interpret it.
  * Example: "What do you think of this article? [https://some_site/article]"
  * This uses a separate model (configurable via `url_model`) to support more URL content with its higher token limit.
* Tokens are used to measure the length of all conversation messages between the Telegram bot assistant and the user. This is useful to:
  * Ensure the length does not go over the model limit. If it does, prune oldest messages to fit within the limit.
  * Remember 50% of the past conversations when starting up TeLLMgramBot again.
* Users can also clear their conversation history for privacy.

## Why Telegram?
Using Telegram as the interface not only solves "exposing" the interface, but gives you boatloads of interactivity over a standard Command Line interface, or trying to create a website with input boxes and submit buttons to try to handle everything:
1. Telegram already lets you paste in verbose, multiline messages.
2. Telegram already lets you paste in pictures, videos, links, etc.
3. Telegram already lets you react with emojis, stickers, etc.

## Supported LLM Providers
TeLLMgramBot selects the LLM provider automatically based on the model name:

| Model prefix | Provider | Example models |
|---|---|---|
| `gpt-` | OpenAI | `gpt-4o`, `gpt-4o-mini`, `gpt-5-mini` |
| `claude-` | Anthropic | `claude-sonnet-4-6`, `claude-haiku-4-5` |

Simply set `chat_model` (and optionally `url_model`) in your `config.yaml` to any supported model and supply the corresponding API key — no other changes needed.

## Directories
When initializing TeLLMgramBot, the following directories get created:
* `configs` - Contains bot configuration files.
  * `config.yaml` (can be a different name)
    * This file sets main bot parameters like naming and the LLM models to use.
    * `chat_model` — the model used for normal conversation (e.g. `gpt-5-mini` or `claude-sonnet-4-6`).
    * `url_model` — the model used to read and summarize URL content, can differ from `chat_model`.
    * An empty `token_limit` will use the maximum tokens supported by the `chat_model`.
  * `tokenGPT.yaml`
    * Contains token size parameters for all supported models.
    * On first run, GPT and Claude model families are pre-populated. Additional models can be added manually.
* `prompts` - Contains prompt files for how the bot interacts with any user.
    * `test_personality.prmpt` (can be a different name)
      * A sample prompt file defining the bot's personality: generic, helpful, and multi-provider-aware.
      * The prompt emphasizes the bot's ability to fetch and analyze URLs passed in square brackets `[]`.
      * The user can create more prompt files as needed for different personalities.
    * `url_analysis.prmpt`
      * Prompt template used to analyze URL content passed in brackets `[]`.
* `errorlogs`
   * Contains a `tellmgrambot_error.log` file to investigate if there are problems during the interaction.
   * User will also get notified to contact the owner.
* `sessionlogs`
  * Every conversation is stored between the Telegram bot assistant and each user.
  * If a user types `/forget`, any session log files between the bot and the user will all be removed.

### Environment Variables
TeLLMgramBot also creates or utilizes the following environment variables that can be pre-loaded especially in other operating systems like Home Assistant, having different configurations for persistent storage:
1. `TELLMGRAMBOT_CONFIGS_PATH`
2. `TELLMGRAMBOT_PROMPTS_PATH`
3. `TELLMGRAMBOT_ERRORLOGS_PATH`
4. `TELLMGRAMBOT_SESSIONLOGS_PATH`

If neither of these are defined, the initialization would use the top-level execution run directory.

## API Keys
To operate TeLLMgramBot, the following API keys are required:
* **[OpenAI](https://platform.openai.com/overview)** — required when using a `gpt-*` model.
* **[Anthropic](https://console.anthropic.com/)** — required when using a `claude-*` model.
* **[Telegram](https://core.telegram.org/api)** — always required; offers a Bot API through BotFather.
* **[VirusTotal](https://www.virustotal.com/gui/home/)** — always required; performs safety checks on URLs.

There are two ways to populate each API key: environment variables or `.key` files.

### Environment Variables
TeLLMgramBot uses the following environment variables for API keys:
1. `TELLMGRAMBOT_OPENAI_API_KEY` *(OpenAI models)*
2. `TELLMGRAMBOT_ANTHROPIC_API_KEY` *(Anthropic models)*
3. `TELLMGRAMBOT_TELEGRAM_API_KEY`
4. `TELLMGRAMBOT_VIRUSTOTAL_API_KEY`

During spin-up time, a user can call out `os.environ[env_var]` to set those variables, like the following example:
```
my_keys = Some_Vault_Fetch_Function()

os.environ['TELLMGRAMBOT_OPENAI_API_KEY']     = my_keys['OpenAIKey']
os.environ['TELLMGRAMBOT_ANTHROPIC_API_KEY']  = my_keys['AnthropicKey']
os.environ['TELLMGRAMBOT_TELEGRAM_API_KEY']   = my_keys['BotFatherToken']
os.environ['TELLMGRAMBOT_VIRUSTOTAL_API_KEY'] = my_keys['VirusTotalToken']
```

This means the user can implement whatever key vault they want to fetch the keys at runtime, without needing files stored in the directory.

### API Key Files
The other route is to create files by the base path during execution or a specified environment variable `TELLMGRAMBOT_KEYS_PATH`. By default, files are created for the user to input each API key:
1. `openai.key`
2. `anthropic.key`
3. `telegram.key`
4. `virustotal.key`

Each file with the associated API key will update its respective environment variable if not defined.

## Bot Setup
This library includes an example script `test_local.py`, which uses files from the folders `configs` and `prompts` for TeLLMgramBot to process.
1. Ensure the previous sections are followed with the proper API keys and your Telegram bot set.
2. Install this library via PIP (`pip install TeLLMgramBot`) and then import into your project.
3. Instantiate the bot by passing in various configuration pieces needed below.
   Note the Telegram bot's full name and username auto-populate before startup.
   ```
   telegram_bot = TeLLMgramBot.TelegramBot(
       bot_owner      = <Bot owner's Telegram username>,
       bot_nickname   = <Bot nickname like 'Botty'>,
       bot_initials   = <Bot initials like 'FB'>,
       chat_model     = <Conversation model like 'gpt-4o-mini' or 'claude-sonnet-4-6'>,
       url_model      = <URL analysis model like 'gpt-4o' or 'claude-haiku-4-5'>,
       token_limit    = <Maximum token count set, by default chat_model max>,
       persona_temp   = <LLM factual to creative value [0-2], by default 1.0>,
       persona_prompt = <System prompt summarizing bot personality>
   )
   ```
4. Turn on TeLLMgramBot by calling:
   ```
   telegram_bot.start_polling()
   ```
   Once you see `TeLLMgramBot polling...`, the bot is online in Telegram.
5. Converse! Type `/help` for all available commands.

## Resources
* GitHub repository [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) has guides to create a Telegram bot.
* For more information on OpenAI models and token limits:
  * [OpenAI model overview and maximum tokens](https://platform.openai.com/docs/models)
  * [OpenAI message conversion to tokens](https://github.com/openai/openai-python)
  * [OpenAI custom fine-tuning](https://platform.openai.com/docs/guides/model-optimization)
  * [OpenAI's tiktoken library](https://github.com/openai/tiktoken/tree/main)
* For more information on Anthropic Claude models:
  * [Anthropic model overview and context windows](https://docs.anthropic.com/en/docs/about-claude/models)
  * [Anthropic Python SDK](https://github.com/anthropic/anthropic-sdk-python)
