TeLLMgramBot 3.2.2__tar.gz → 3.4.0__tar.gz

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.2.2
+Version: 3.4.0
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -16,7 +16,7 @@ Requires-Dist: httpx
 Requires-Dist: beautifulsoup4
 Requires-Dist: validators
 Requires-Dist: tiktoken>=0.12
-Requires-Dist: python-telegram-bot>20.0
+Requires-Dist: python-telegram-bot>=20.8
 Requires-Dist: aiosqlite>=0.19
 Dynamic: author
 Dynamic: author-email
@@ -45,14 +45,15 @@ The basic goal of this project is to create a bridge between a Telegram Bot and
   * Ensure the length does not go over the model limit. If it does, prune oldest messages to fit within the limit.
   * Remember past conversations when restarting: loads the user's full history across all chats (private and groups) plus all other participants' messages in the current chat, up to 50% of the token budget. In private chats, shared group context (messages from groups where both user and bot are active) fills the remaining budget, enabling the bot to reference group conversations from a private context. This eliminates amnesia when users switch between contexts.
 * Users can manage privacy via two commands:
-  * `/forget` — In private chats, clears the full conversation (including bot replies) and resets all of your active sessions (any sessions where your context was merged). In group chats, removes your messages across all chat types; other participants' messages and sessions remain.
-  * `/private` — Toggles per-user private mode (private chats only). When ON, messages are excluded from group conversation contexts, enabling selective privacy even in shared groups. If you have private mode ON and message a group, the bot will remind you once per session.
+  * `/forget` — In private chats, clears the full conversation (including bot replies) and resets all of your active sessions (any sessions where your context was merged). In group chats, removes your messages across all chat types and cleans up paired bot replies; other participants' messages and sessions remain.
+  * `/private` — Toggles per-user private mode (private chats only). When ON, messages are excluded from group conversation contexts, enabling selective privacy even in shared groups.
 
 ## 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.
+4. Telegram message reactions (👀) provide a lightweight read receipt without breaking conversation flow.
 
 ## Supported LLM Providers
 TeLLMgramBot selects the LLM provider automatically based on the model name:
@@ -80,6 +81,9 @@ When initializing TeLLMgramBot, the following directories get created:
       * 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.
+    * `system_appendix.prmpt`
+      * Framework-owned behavioral guidance automatically appended to the persona prompt at runtime.
+      * Teaches the LLM how cross-chat memory works (cross-pollination, private mode, shared group context) without requiring persona authors to include this guidance.
     * `url_analysis.prmpt`
       * Prompt template used to analyze URL content passed in brackets `[]`.
 * `errorlogs`
@@ -137,6 +141,18 @@ By default, API key files are created in the execution directory (or the directo
 
 Each file with the associated API key will update its respective environment variable if not defined. Missing provider keys (OpenAI or Anthropic) will disable chat and URL analysis but allow the bot to start. Missing VirusTotal keys will disable URL analysis.
 
+## Commands and Interactions
+
+### Read Receipt Acknowledgement (Group Chats Only)
+In group and supergroup chats, you can request the bot to acknowledge reading your message with a lightweight 👀 reaction instead of waiting for a full response. Simply mention the bot's username, nickname, or initials followed by an explicit request:
+
+- `@botname acknowledge`
+- `botname mark as read`
+- `BN did you read that?`
+- `botname confirm you received`
+
+The bot will respond with a 👀 reaction emoji on your message (if the Telegram client supports message reactions), or with a short "Got it!" reply as fallback. Read receipt requests are processed immediately without touching the conversation context, making them ideal for confirming the bot is online without disrupting group flow.
+
 ## 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.

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/README.md

@@ -14,14 +14,15 @@ The basic goal of this project is to create a bridge between a Telegram Bot and
   * Ensure the length does not go over the model limit. If it does, prune oldest messages to fit within the limit.
   * Remember past conversations when restarting: loads the user's full history across all chats (private and groups) plus all other participants' messages in the current chat, up to 50% of the token budget. In private chats, shared group context (messages from groups where both user and bot are active) fills the remaining budget, enabling the bot to reference group conversations from a private context. This eliminates amnesia when users switch between contexts.
 * Users can manage privacy via two commands:
-  * `/forget` — In private chats, clears the full conversation (including bot replies) and resets all of your active sessions (any sessions where your context was merged). In group chats, removes your messages across all chat types; other participants' messages and sessions remain.
-  * `/private` — Toggles per-user private mode (private chats only). When ON, messages are excluded from group conversation contexts, enabling selective privacy even in shared groups. If you have private mode ON and message a group, the bot will remind you once per session.
+  * `/forget` — In private chats, clears the full conversation (including bot replies) and resets all of your active sessions (any sessions where your context was merged). In group chats, removes your messages across all chat types and cleans up paired bot replies; other participants' messages and sessions remain.
+  * `/private` — Toggles per-user private mode (private chats only). When ON, messages are excluded from group conversation contexts, enabling selective privacy even in shared groups.
 
 ## 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.
+4. Telegram message reactions (👀) provide a lightweight read receipt without breaking conversation flow.
 
 ## Supported LLM Providers
 TeLLMgramBot selects the LLM provider automatically based on the model name:
@@ -49,6 +50,9 @@ When initializing TeLLMgramBot, the following directories get created:
       * 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.
+    * `system_appendix.prmpt`
+      * Framework-owned behavioral guidance automatically appended to the persona prompt at runtime.
+      * Teaches the LLM how cross-chat memory works (cross-pollination, private mode, shared group context) without requiring persona authors to include this guidance.
     * `url_analysis.prmpt`
       * Prompt template used to analyze URL content passed in brackets `[]`.
 * `errorlogs`
@@ -106,6 +110,18 @@ By default, API key files are created in the execution directory (or the directo
 
 Each file with the associated API key will update its respective environment variable if not defined. Missing provider keys (OpenAI or Anthropic) will disable chat and URL analysis but allow the bot to start. Missing VirusTotal keys will disable URL analysis.
 
+## Commands and Interactions
+
+### Read Receipt Acknowledgement (Group Chats Only)
+In group and supergroup chats, you can request the bot to acknowledge reading your message with a lightweight 👀 reaction instead of waiting for a full response. Simply mention the bot's username, nickname, or initials followed by an explicit request:
+
+- `@botname acknowledge`
+- `botname mark as read`
+- `BN did you read that?`
+- `botname confirm you received`
+
+The bot will respond with a 👀 reaction emoji on your message (if the Telegram client supports message reactions), or with a short "Got it!" reply as fallback. Read receipt requests are processed immediately without touching the conversation context, making them ideal for confirming the bot is online without disrupting group flow.
+
 ## 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.

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/TeLLMgramBot/TeLLMgramBot.py

@@ -5,16 +5,32 @@ import json
 import asyncio
 from tempfile import gettempdir
 from math import floor
-from telegram import Bot, Update, Message, Chat, User
+from telegram import Bot, Update, Message, Chat, User, ReactionTypeEmoji
+from telegram.error import TelegramError
 from telegram.constants import MessageLimit
 from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes
+
 from .providers.factory import get_provider
 from .providers.base import ContextLengthExceededError, ProviderAuthError, ProviderConnectionError
-from .initialize import INIT_BOT_CONFIG, ApiKeyStatus, init_structure, init_bot_config, init_bot_prompt
+from .initialize import (
+    INIT_BOT_CONFIG,
+    ApiKeyStatus,
+    init_structure,
+    init_bot_config,
+    init_bot_prompt,
+    init_system_appendix,
+)
 from .conversation import Conversation
-from .database import get_private_mode, set_private_mode, delete_messages_for_user, delete_messages_for_chat, delete_private_messages_for_user
+from .database import (
+    get_private_mode,
+    set_private_mode,
+    delete_messages_for_user,
+    delete_messages_for_chat,
+    delete_private_messages_for_user,
+    delete_paired_bot_replies,
+)
 from .models import TokenLimits
-from .message_handlers import handle_greetings, handle_common_queries, handle_url_ask
+from .message_handlers import handle_greetings, handle_common_queries, handle_url_ask, handle_read_receipt
 from .utils import read_yaml, read_text, exact_word_match, generate_error_path, log_error
 
 class TelegramBot:
@@ -93,12 +109,14 @@ class TelegramBot:
         Remove conversation history from the database (behavior depends on chat type).
 
         In private chats: deletes all messages in the private chat (including bot replies).
-        In group chats: deletes the user's rows across all chats (private included).
+        In group chats: deletes the user's rows across all chats (private included), then
+        deletes bot replies in the current chat that were paired with the user's messages
+        or were orphaned by a previous /forget call, leaving other users' conversations intact.
 
         In both cases, evicts only the in-memory Conversation objects that contain this
         user's data - scoped to the current chat, the user's private chat, and any other
         chats where their context was previously merged. Other users' active sessions are
-        not affected. All private-mode notices for this user are also cleared.
+        not affected.
         """
         user_id = update.message.from_user.id
         chat_id = update.message.chat.id
@@ -116,13 +134,14 @@ class TelegramBot:
             await delete_messages_for_chat(chat_id)
         else:
             await delete_messages_for_user(user_id)
+            # Delete bot replies paired to this user's messages, plus any pre-existing
+            # orphaned assistant rows left by earlier /forget calls in this chat.
+            await delete_paired_bot_replies(chat_id, self.telegram['bot_id'])
 
         # Evict only the Conversations that contain this user's data, not all sessions.
         for evict_id in user_chat_ids:
             self.conversations.pop(evict_id, None)
             self.token_warning.pop(evict_id, None)
-        # Clear all private-mode notices for this user across all chats.
-        self._private_mode_warned = {k for k in self._private_mode_warned if k[1] != user_id}
 
         await update.message.reply_text("My memories of our conversations are wiped!")
 
@@ -244,19 +263,6 @@ class TelegramBot:
         is_private = (chat_type == 'private') and user_private_mode
         await conv.add_user_message(text, user_id, username, is_private)
 
-        # Warn once per group session if the user has private mode ON.
-        # Their private-chat messages are excluded from this group's context, which can be
-        # surprising. The notice is appended to the first reply in the session for this user.
-        private_mode_notice = ""
-        if chat_type in ('group', 'supergroup') and user_private_mode:
-            warn_key = (chat_id, user_id)
-            if warn_key not in self._private_mode_warned:
-                self._private_mode_warned.add(warn_key)
-                private_mode_notice = (
-                    "\n\n(Note: your private mode is ON - messages from our private chat "
-                    "are not included in this group's context. To disable, send /private off in our DMs.)"
-                )
-
         # Check if the user is asking about a [URL]
         url_match = re.search(r'\[http(s)?://\S+]', text)
 
@@ -273,9 +279,6 @@ class TelegramBot:
             # This is the transition point between quick Telegram replies and the LLM
             reply = await self.llm_completion(chat_id)
 
-        if private_mode_notice:
-            reply += private_mode_notice
-
         # Check token count before storing to determine if warning should be appended
         token_count = await conv.get_message_token_count()
         if token_count > self.chatgpt['prune_back_to'] and chat_id not in self.token_warning:
@@ -300,6 +303,27 @@ class TelegramBot:
 
         return reply
 
+    async def _send_read_receipt(self, msg: Message, context: ContextTypes.DEFAULT_TYPE):
+        """
+        Send a read receipt acknowledgement via message reaction.
+
+        Attempts to add a eyes-emoji reaction to the user's message to confirm the bot
+        read it, avoiding a full LLM response. If the message reaction API is unavailable
+        (e.g., older Telegram clients), falls back to a short "Got it!" text reply.
+
+        Args:
+            msg: The Telegram Message object to react to.
+            context: The Telegram context for sending the reply if reaction fails.
+        """
+        try:
+            await context.bot.set_message_reaction(
+                chat_id=msg.chat.id,
+                message_id=msg.message_id,
+                reaction=[ReactionTypeEmoji(emoji="👀")],
+            )
+        except (TelegramError, AttributeError):
+            await msg.reply_text("Got it!")
+
     async def tele_handle_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
         """Handles the Telegram side of the message, discerning between Private and Group conversation."""
         validated = await self.tele_validate(update)
@@ -314,11 +338,17 @@ class TelegramBot:
             if exact_word_match(self.telegram['username'], msg.text):
                 pattern = r'@?\b' + re.escape(self.telegram['username']) + r'\b'
                 new_text = re.sub(pattern, '', msg.text).strip()
+                if handle_read_receipt(new_text):
+                    await self._send_read_receipt(msg, context)
+                    return
                 response = await self.tele_handle_response(new_text, msg)
             elif (
                 exact_word_match(self.telegram['nickname'], msg.text) or
                 exact_word_match(self.telegram['initials'], msg.text)
             ):
+                if handle_read_receipt(msg.text):
+                    await self._send_read_receipt(msg, context)
+                    return
                 response = await self.tele_handle_response(msg.text, msg)
             else:
                 return
@@ -448,7 +478,6 @@ class TelegramBot:
         self.error_log = generate_error_path()
         self.token_warning = {}  # Determines whether user has reached token limit by AI model
         self.conversations = {}  # Provides Conversation class per user based on bot response
-        self._private_mode_warned = set()  # (chat_id, user_id) pairs that received the private mode notice
         self.telegram = {
             'bot_id'       : 0,  # overwritten by _tele_info(); 0 is a safe sentinel
             'owner'        : bot_owner,
@@ -501,8 +530,9 @@ class TelegramBot:
 
         Reads bot settings from the specified YAML configuration file and prompt file,
         applies defaults for any missing values, and returns a fully initialized TelegramBot.
-        Also calls init_structure() to bootstrap directories and API keys, and returns
-        the resulting ApiKeyStatus to gate features.
+        Also calls init_structure() to bootstrap directories and API keys. Automatically
+        appends the system appendix to the persona prompt at runtime, providing framework-owned
+        behavioral guidance that teaches the LLM about cross-chat memory semantics.
 
         Args:
             config_file: Path to bot configuration YAML file (default: 'config.yaml').
@@ -513,6 +543,8 @@ class TelegramBot:
 
         Side Effects:
             - Calls init_structure() which may create directories and check API keys.
+            - Calls init_system_appendix() which creates system_appendix.prmpt if missing.
+            - Appends system appendix to persona prompt before instantiation.
             - May print warning messages if configuration values are missing or prompt file is empty.
         """
         # First provide the main structure if not already there; capture API key status
@@ -521,6 +553,7 @@ class TelegramBot:
         # Ensure both bot configuration and prompt files are defined and readable
         config = read_yaml(init_bot_config(config_file))
         prompt = read_text(init_bot_prompt(prompt_file))
+        appendix = init_system_appendix()
 
         # Check any configuration values missing and apply default values:
         for parameter, value in INIT_BOT_CONFIG.items():
@@ -535,6 +568,12 @@ class TelegramBot:
                 if value:
                     print(f"Configuration '{parameter}' not defined, set to '{value}'")
 
+        # Append the framework-owned system appendix to the persona prompt.
+        # The appendix teaches every soul how cross-chat memory works, so the
+        # persona author doesn't need to include this guidance themselves.
+        if appendix:
+            prompt = prompt.rstrip() + "\n\n" + appendix
+
         # Apply parameters to bot:
         return TelegramBot(
             bot_owner      = config['bot_owner'],

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/TeLLMgramBot/conversation.py

@@ -183,9 +183,12 @@ class Conversation:
         bot answer questions about group conversations from a private chat context.
 
         Per-user idempotent: once a user's cursor is set, subsequent calls return True immediately.
-        Calling for a new user_id merges that user's cross-chat context into the existing
-        conversation. Context is considered "found" only if messages were actually inserted
-        (rows_inserted > 0 or group_rows_inserted > 0).
+        This guard handles concurrent message arrival: if two messages from the same user arrive
+        before the first load completes and both check the cursor, the second call hits the early
+        return and skips a duplicate load, ensuring single-pass context loading even under race
+        conditions. Calling for a new user_id merges that user's cross-chat context into the
+        existing conversation. Context is considered "found" only if messages were actually
+        inserted (rows_inserted > 0 or group_rows_inserted > 0).
 
         Args:
             token_limit: The maximum token count to load into the in-memory context.
@@ -203,10 +206,11 @@ class Conversation:
             - Sets self._context_cursor[user_id] to the max message id loaded once context is found.
             - Sets self._history_end[user_id] to len(self.messages) after loading, marking the
               boundary between historical context and live session messages for future refreshes.
-            - Prints to stdout showing token count and whether the token limit was reached.
+            - Prints context loading summary (Full/Partial context with token count) if history found,
+              or "No prior context" message if no history exists (removed: early-return and refresh
+              diagnostics to reduce noisy logging).
         """
         if user_id in self._context_cursor:
-            print(f"Context already loaded for User {user_id} in {self.chat_print}")
             return True
 
         exclude_private = True
@@ -323,7 +327,6 @@ class Conversation:
         if rows_inserted > 0:
             self._context_cursor[user_id] = current_max
             self._history_end[user_id] = insert_pos + rows_inserted
-            print(f"Refreshed {rows_inserted} new message(s) for User {user_id} in {self.chat_print}")
 
         return rows_inserted > 0
 

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/TeLLMgramBot/database.py

@@ -159,15 +159,12 @@ async def load_full_user_context(
 
     In Telegram, a user's private chat_id always equals their user_id. Three arms cover
     all cross-context cases:
-
       Arm 1 - chat_id = current_chat_id:
           All messages (user and bot) in the current chat. Always included.
-
       Arm 2 - chat_id = user_id AND chat_id != current_chat_id:
           All messages (both sides) from the user's private chat, included when the
           current chat is a group. Pulling both sides restores proper role alternation
           that was broken when only the user's own rows were fetched.
-
       Arm 3 - user_id = user_id AND chat_id != current_chat_id AND chat_id != user_id:
           The requesting user's own messages from any other group chats (not the private
           chat, not the current chat). Covers group-to-private and group-to-group context.
@@ -341,6 +338,47 @@ async def load_shared_group_context(
     all_rows.sort(key=lambda r: (r[2], r[3]))
     return [{"role": row[0], "content": row[1]} for row in all_rows]
 
+async def delete_paired_bot_replies(chat_id: int, bot_id: int) -> None:
+    """
+    Delete bot reply rows in a group chat that are paired with deleted user messages or orphaned.
+
+    Handles two cases in one pass:
+    1. Paired bot replies: after delete_messages_for_user() removes a user's rows, the bot
+       replies that immediately followed those messages become orphaned (no user row before
+       them). These are caught by the orphan query below.
+    2. Pre-existing orphans: assistant rows left behind by earlier /forget calls that deleted
+       user rows but not their paired replies. Cleaned up opportunistically on every group
+       /forget to heal historical debris.
+
+    Both cases are unified by a single query: delete assistant rows whose immediately preceding
+    message in the same chat is not a user message. Reliable because the bot processes messages
+    sequentially - each reply is stored immediately after its user message, so the immediately
+    preceding row unambiguously identifies the pairing. Other users' conversations are unaffected
+    as long as their user rows remain (their user rows serve as the preceding message for their
+    own bot replies).
+
+    Args:
+        chat_id: Telegram chat ID of the group chat to clean up.
+        bot_id: Telegram user ID of the bot account (identifies assistant rows by user_id).
+    """
+    async with aiosqlite.connect(get_db_path()) as db:
+        await db.execute(
+            "DELETE FROM messages "
+            "WHERE chat_id = ? AND role = 'assistant' AND user_id = ? "
+            "AND NOT EXISTS ("
+            "    SELECT 1 FROM messages prev "
+            "    WHERE prev.chat_id = messages.chat_id "
+            "      AND prev.id = ("
+            "          SELECT MAX(m2.id) FROM messages m2 "
+            "          WHERE m2.chat_id = messages.chat_id "
+            "            AND m2.id < messages.id"
+            "      ) "
+            "      AND prev.role = 'user'"
+            ")",
+            (chat_id, bot_id),
+        )
+        await db.commit()
+
 async def delete_messages_for_user(user_id: int) -> None:
     """
     Delete all message rows for a given user_id across all chats.

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/TeLLMgramBot/initialize.py

@@ -316,6 +316,57 @@ def init_bot_prompt(file='test_personality.prmpt') -> str:
     except Exception:
         sys.exit(f"Error while generating {env_var} file '{file}'! Exiting...")
 
+def init_system_appendix(file='system_appendix.prmpt') -> str:
+    """
+    Ensure the system appendix prompt file is created and return its contents.
+
+    The system appendix is a framework-owned behavioral block automatically appended
+    to every user-defined persona prompt at runtime. It teaches the bot how its
+    cross-chat memory works, so the persona author does not need to include this
+    guidance. Every soul (persona) gets the same nervous system (memory behavior).
+
+    The appendix covers:
+    - Cross-chat context is intentional and consensual, controlled by /private
+    - Group sessions include the user's private chat history (cross-pollination)
+    - Private sessions include shared group chat history (h7bz)
+    - Absence of /private means the user opted into cross-chat memory sharing
+    - /private ON means only that user's private messages are excluded; all other
+      cross-chat context remains available
+    - Never deny having context that was actually provided
+
+    Advanced users may edit system_appendix.prmpt to customize this behavior.
+    The url_analysis.prmpt prompt is separate and unaffected.
+
+    Args:
+        file: Name of the system appendix prompt file (default: 'system_appendix.prmpt').
+
+    Returns:
+        The contents of the system appendix prompt file.
+    """
+    env_var = "TELLMGRAMBOT_PROMPTS_PATH"
+    try:
+        return read_text(generate_file_path(os.environ[env_var], file, "system appendix prompt",
+            "You have persistent memory across conversations. Past interactions are selectively "
+            "loaded into your current context window based on relevance and token budget. Treat "
+            "anything visible in your current conversation history as reliable memory.\n\n"
+            "Cross-chat memory rules (apply only to what is present in your current context):\n"
+            "- In a group chat: when the user's private chat history with you is included in your "
+            "current context (cross-pollination), use it naturally. Do not deny having context "
+            "that is visible to you.\n"
+            "- In a private chat: when shared group chat history from groups where both you and "
+            "the user are active is included in your current context, use it to answer questions "
+            "about those group conversations. Do not deny having context that is visible to you.\n"
+            "- If a user has /private mode ON, their private-chat messages are excluded from group "
+            "contexts. You may acknowledge this if relevant, but do not generalize it to deny all "
+            "cross-chat context that is present in your current history.\n"
+            "- Never deny having context that is present in the messages you can currently see. "
+            "Use what you know confidently.\n"
+        ))
+    except KeyError:
+        sys.exit(f"{env_var} must be defined to create file '{file}'! Exiting...")
+    except Exception:
+        sys.exit(f"Error while generating {env_var} file '{file}'! Exiting...")
+
 def init_url_prompt(file='url_analysis.prmpt') -> str:
     """
     Ensure prompt file is created that defines how the bot will analyze URLs via square brackets [].
@@ -366,4 +417,5 @@ if __name__ == '__main__':
     init_structure()
     init_bot_config()
     init_bot_prompt()
+    init_system_appendix()
     print("TeLLMgramBot setup complete!")

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/TeLLMgramBot/message_handlers.py

@@ -5,7 +5,13 @@ import validators
 
 from .initialize import init_url_prompt
 from .models import TokenLimits
-from .web_utils import fetch_url, strip_html_markup, InvalidURLException, InsecureURLException, SusURLException
+from .web_utils import (
+    fetch_url,
+    strip_html_markup,
+    InvalidURLException,
+    InsecureURLException,
+    SusURLException,
+)
 from .providers.factory import get_provider
 
 def handle_greetings(text: str) -> Optional[str]:
@@ -21,6 +27,28 @@ def handle_greetings(text: str) -> Optional[str]:
         return f'{word}!'
     return None
 
+def handle_read_receipt(text: str) -> bool:
+    """
+    Detect explicit user requests for read receipt acknowledgement.
+
+    Matches explicit acknowledgement trigger phrases: "acknowledge", "acknowledged", "mark as read",
+    "read receipt", "did you read", "did you get that", and "confirm you received". Uses word-boundary
+    matching to avoid false positives from casual conversation (e.g., "unacknowledged" does not match).
+
+    Args:
+        text: The message text to analyze (typically after bot mention/nickname stripped).
+
+    Returns:
+        True if the message matches a read receipt trigger phrase; False otherwise.
+    """
+    text_clean = re.sub(r'[^\w\s]', '', text.lower().strip())
+    triggers = {
+        'acknowledge', 'acknowledged', 'mark as read',
+        'read receipt', 'did you read', 'did you get that',
+        'confirm you received',
+    }
+    return any(re.search(rf'\b{re.escape(t)}\b', text_clean) is not None for t in triggers)
+
 def handle_common_queries(text: str) -> Optional[str]:
     """
     Send messages for assistant bot to respond quickly with some example phrases:

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/TeLLMgramBot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.2.2
+Version: 3.4.0
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -16,7 +16,7 @@ Requires-Dist: httpx
 Requires-Dist: beautifulsoup4
 Requires-Dist: validators
 Requires-Dist: tiktoken>=0.12
-Requires-Dist: python-telegram-bot>20.0
+Requires-Dist: python-telegram-bot>=20.8
 Requires-Dist: aiosqlite>=0.19
 Dynamic: author
 Dynamic: author-email
@@ -45,14 +45,15 @@ The basic goal of this project is to create a bridge between a Telegram Bot and
   * Ensure the length does not go over the model limit. If it does, prune oldest messages to fit within the limit.
   * Remember past conversations when restarting: loads the user's full history across all chats (private and groups) plus all other participants' messages in the current chat, up to 50% of the token budget. In private chats, shared group context (messages from groups where both user and bot are active) fills the remaining budget, enabling the bot to reference group conversations from a private context. This eliminates amnesia when users switch between contexts.
 * Users can manage privacy via two commands:
-  * `/forget` — In private chats, clears the full conversation (including bot replies) and resets all of your active sessions (any sessions where your context was merged). In group chats, removes your messages across all chat types; other participants' messages and sessions remain.
-  * `/private` — Toggles per-user private mode (private chats only). When ON, messages are excluded from group conversation contexts, enabling selective privacy even in shared groups. If you have private mode ON and message a group, the bot will remind you once per session.
+  * `/forget` — In private chats, clears the full conversation (including bot replies) and resets all of your active sessions (any sessions where your context was merged). In group chats, removes your messages across all chat types and cleans up paired bot replies; other participants' messages and sessions remain.
+  * `/private` — Toggles per-user private mode (private chats only). When ON, messages are excluded from group conversation contexts, enabling selective privacy even in shared groups.
 
 ## 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.
+4. Telegram message reactions (👀) provide a lightweight read receipt without breaking conversation flow.
 
 ## Supported LLM Providers
 TeLLMgramBot selects the LLM provider automatically based on the model name:
@@ -80,6 +81,9 @@ When initializing TeLLMgramBot, the following directories get created:
       * 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.
+    * `system_appendix.prmpt`
+      * Framework-owned behavioral guidance automatically appended to the persona prompt at runtime.
+      * Teaches the LLM how cross-chat memory works (cross-pollination, private mode, shared group context) without requiring persona authors to include this guidance.
     * `url_analysis.prmpt`
       * Prompt template used to analyze URL content passed in brackets `[]`.
 * `errorlogs`
@@ -137,6 +141,18 @@ By default, API key files are created in the execution directory (or the directo
 
 Each file with the associated API key will update its respective environment variable if not defined. Missing provider keys (OpenAI or Anthropic) will disable chat and URL analysis but allow the bot to start. Missing VirusTotal keys will disable URL analysis.
 
+## Commands and Interactions
+
+### Read Receipt Acknowledgement (Group Chats Only)
+In group and supergroup chats, you can request the bot to acknowledge reading your message with a lightweight 👀 reaction instead of waiting for a full response. Simply mention the bot's username, nickname, or initials followed by an explicit request:
+
+- `@botname acknowledge`
+- `botname mark as read`
+- `BN did you read that?`
+- `botname confirm you received`
+
+The bot will respond with a 👀 reaction emoji on your message (if the Telegram client supports message reactions), or with a short "Got it!" reply as fallback. Read receipt requests are processed immediately without touching the conversation context, making them ideal for confirming the bot is online without disrupting group flow.
+
 ## 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.

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/TeLLMgramBot.egg-info/requires.txt

@@ -5,5 +5,5 @@ httpx
 beautifulsoup4
 validators
 tiktoken>=0.12
-python-telegram-bot>20.0
+python-telegram-bot>=20.8
 aiosqlite>=0.19

{tellmgrambot-3.2.2 → tellmgrambot-3.4.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setup(
     name='TeLLMgramBot',
-    version='3.2.2',
+    version='3.4.0',
     packages=find_packages(),
     license='MIT',
     author='Digital Heresy',
@@ -22,7 +22,7 @@ setup(
         'beautifulsoup4',
         'validators',
         'tiktoken>=0.12',
-        'python-telegram-bot>20.0',
+        'python-telegram-bot>=20.8',
         'aiosqlite>=0.19'
     ],
     python_requires='>=3.10'