TeLLMgramBot 3.14.0__tar.gz → 3.14.2__tar.gz

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.14.0
+Version: 3.14.2
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -83,6 +83,7 @@ TeLLMgramBot creates the following directories:
   - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory and search behavior. User messages include speaker annotations with chat context and timestamps so the LLM always knows who is speaking, in which chat, and when.
 - **`logs`** - Bot instance logs (one per startup, named after the bot's Telegram username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
   - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `instance_name` when configured).
+  - Log file timestamps are UTC in `[YYYY-MM-DD HH:MM:SS.mmm]` format.
   - Bot keeps the 10 most recent logs per bot instance, automatically pruning older ones.
   - Pass `-v` or `--verbose` on startup for DEBUG-level logging.
 - **`data`** - SQLite database (default `conversations.db`, customizable via `instance_name` config) storing all messages, users, and chats
@@ -167,9 +168,9 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    ```python
    from TeLLMgramBot import TelegramBot
    telegram_bot = TelegramBot.set()
-   telegram_bot.start_polling()
+   telegram_bot.poll()
    ```
-   Once you see `TeLLMgramBot polling...`, the bot is online.
+   Once you see `TeLLMgramBot polling started`, the bot is online.
 6. Type `/help` in Telegram to see all available commands.
 
 ## Resources

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/README.md

@@ -51,6 +51,7 @@ TeLLMgramBot creates the following directories:
   - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory and search behavior. User messages include speaker annotations with chat context and timestamps so the LLM always knows who is speaking, in which chat, and when.
 - **`logs`** - Bot instance logs (one per startup, named after the bot's Telegram username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
   - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `instance_name` when configured).
+  - Log file timestamps are UTC in `[YYYY-MM-DD HH:MM:SS.mmm]` format.
   - Bot keeps the 10 most recent logs per bot instance, automatically pruning older ones.
   - Pass `-v` or `--verbose` on startup for DEBUG-level logging.
 - **`data`** - SQLite database (default `conversations.db`, customizable via `instance_name` config) storing all messages, users, and chats
@@ -135,9 +136,9 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    ```python
    from TeLLMgramBot import TelegramBot
    telegram_bot = TelegramBot.set()
-   telegram_bot.start_polling()
+   telegram_bot.poll()
    ```
-   Once you see `TeLLMgramBot polling...`, the bot is online.
+   Once you see `TeLLMgramBot polling started`, the bot is online.
 6. Type `/help` in Telegram to see all available commands.
 
 ## Resources

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/TeLLMgramBot/TeLLMgramBot.py

@@ -38,7 +38,6 @@ from .initialize import (
     INIT_BOT_CONFIG,
     ApiKeyStatus,
     bind_log_identity,
-    init_logging,
     init_structure,
 )
 from .message_handlers import handle_greetings, handle_common_queries, handle_url_ask
@@ -410,7 +409,7 @@ class TelegramBot:
                 "from group conversation contexts. Use /private off to disable."
             )
 
-    async def tele_handle_response(self, text: str, msg: Message, context_prefix: str = '') -> tuple[str, int | None]:
+    async def tele_handle_response(self, text: str, msg: Message) -> tuple[str, int | None]:
         """
         Primary function for handling any response including Generative AI, ensuring:
         - The owner started up the bot assistant for user interactions.
@@ -429,8 +428,6 @@ class TelegramBot:
         Args:
             text: The user's message text.
             msg: The Telegram Message object containing chat/user context.
-            context_prefix: Optional context prepended to the message before the live
-                           speaker annotation. Used for reply-to-thread context. Defaults to ''.
 
         Returns:
             Tuple of (response_text, assistant_db_id). response_text is the bot's response
@@ -442,6 +439,7 @@ class TelegramBot:
             - Adds user message to conversation history (keyed by chat_id).
             - Upserts user (first_name, last_name, username) and chat metadata.
             - Loads past interactions if this is the first message in this chat_id.
+            - Surfaces the replied-to message into context via _surface_replied_to_message().
             - May invoke LLM tool calling (search_messages) and perform a second LLM round-trip.
             - Generates a token warning if conversation nears the limit.
             - Prunes conversation if token count exceeds the threshold.
@@ -489,6 +487,9 @@ class TelegramBot:
             # Already loaded - check for new cross-chat messages since last load.
             await conv.refresh_user_context(user_id, token_budget)
 
+        # Surface the replied-to message into context before adding the triggering message.
+        await self._surface_replied_to_message(msg, conv)
+
         # Short-circuit for trivial greetings/queries - not persisted to conversation history
         quick_reply = handle_greetings(text) or handle_common_queries(text)
         if quick_reply:
@@ -499,7 +500,7 @@ class TelegramBot:
         user_private_mode = await get_private_mode(user_id)
         is_private = (chat_type == 'private') and user_private_mode
         user_msg_id = await conv.add_user_message(
-            text, user_id, username, first_name, last_name, is_private, context_prefix, msg.message_id
+            text, user_id, username, first_name, last_name, is_private, msg.message_id
         )
 
         # Check if the user is asking about a [URL]
@@ -507,10 +508,10 @@ class TelegramBot:
 
         # Form the assistant's message based on low level easy stuff or send to the LLM
         reply = _MSG_PROCESS_ERROR
-        if url_match and self.key_status.url_analysis_enabled:
+        if url_match and self._key_status.url_analysis_enabled:
             await msg.reply_text("Sure, give me a moment to look at that URL...")
             reply = await handle_url_ask(text, self.llm['url_model'], conv.system_content)
-        elif self._online and self.key_status.chat_enabled:
+        elif self._online and self._key_status.chat_enabled:
             # This is the transition point between quick Telegram replies and the LLM.
             tools = self._build_tool_list(chat_type, username)
             result = await self.llm_completion(chat_id, tools)
@@ -549,65 +550,51 @@ class TelegramBot:
 
         return reply, assistant_db_id
 
-    async def _build_reply_context(self, msg: Message) -> str:
+    async def _surface_replied_to_message(self, msg: Message, conv: Conversation) -> None:
         """
-        Build an inline context prefix when the user is replying to another message.
-
-        Used to surface context when the triggering message is a reply-to another message
-        not already in the conversation's memory window. Returns an annotated prefix string
-        with speaker name and timestamp if the replied-to message is not in context, or an
-        empty string if already present.
-
-        Deduplication applies only to our own bot's replies (to avoid repeating content
-        already visible in context). For all other senders - foreign bots and human users -
-        the prefix is always prepended so the LLM has an explicit anchor to the referenced
-        message regardless of whether it appears elsewhere in the loaded context.
-
-        Own-bot dedup uses two tiers:
-        1. Memory - reply_to_message.message_id in conv._loaded_message_ids (O(1)).
-           In-session bot replies are added here immediately after each send.
-        2. DB fallback - query for tg_message_id in the messages table.
-           Cross-session bot replies are findable here since tg_message_id is now
-           stored for assistant messages after each send.
-
-        Fires in all chat types (group and private) when reply_to_message exists and has text.
-        from_user is not required — messages from channel-linked bots or anonymous admins
-        may omit it; sender_chat.title or 'unknown' is used as the name fallback.
-        Correctly re-surfaces bot messages that are no longer in context (e.g. post-/forget).
+        Persist and inject the replied-to message into conversation context.
+
+        Replaces the old prefix-string approach: instead of prepending replied-to content
+        to the triggering message, the replied-to message is injected as its own entry in
+        conv.messages (and stored to DB if not already there), matching the format used
+        for DB-loaded messages.
+
+        Three cases:
+          Own bot: inject as role='assistant' with raw content (no speaker prefix). If not
+            already in DB (checked via message_id_exists), persists via upsert_user (bot_id
+            as user), upsert_chat, and insert_message with created_at=reply.date. Covers
+            both post-/forget (not in DB) and outside-token-window (in DB but not loaded).
+          Foreign bot or regular user with from_user: if not already in DB, insert with
+            original timestamp (upsert_user, upsert_chat, insert_message with created_at).
+            Inject as role='user' with '[Replying to Name, dt]:' format for explicit context.
+          from_user=None (channel-linked bot, anonymous admin): inject only - no DB write
+            since there is no user_id to reference.
+
+        No-op if msg has no reply, the reply has no text, or the replied-to message is
+        already in conv._loaded_message_ids (already in context window).
 
         Args:
             msg: The incoming Telegram Message that triggered the bot.
-
-        Returns:
-            Formatted prefix string, e.g.
-            "[BotB, 2026-04-05 14:30 UTC]: The ancient sword was forged in...\n"
-            or empty string if the replied-to message is already in context.
+            conv: The active Conversation for this chat.
         """
         reply = msg.reply_to_message
         if not reply or not reply.text:
-            return ''
+            return
 
         r_tg_id = reply.message_id
-        conv = self.conversations.get(msg.chat.id)
+        if r_tg_id in conv._loaded_message_ids:
+            return
+
         is_our_reply = (
             reply.from_user is not None and
             reply.from_user.id == self.telegram['bot_id']
         )
+        is_foreign_bot = (
+            reply.from_user is not None and
+            reply.from_user.is_bot and
+            not is_our_reply
+        )
 
-        if is_our_reply:
-            # Dedup only our own bot's replies to avoid repeating content already visible.
-            # Tier 1: in-session check via loaded message ID set
-            if conv and r_tg_id in conv._loaded_message_ids:
-                return ''
-            # Tier 2: DB fallback for cross-session bot replies
-            if await message_id_exists(msg.chat.id, r_tg_id):
-                return ''
-
-        # For own-bot replies, mark as seen to skip dedup on subsequent replies
-        # to the same message within the session. Foreign/human IDs are tracked
-        # by tele_handle_message after the response is sent.
-        if is_our_reply and conv:
-            conv._loaded_message_ids.add(r_tg_id)
         if reply.from_user:
             sender = reply.from_user
             name_parts = [p for p in [sender.first_name, sender.last_name] if p]
@@ -616,16 +603,76 @@ class TelegramBot:
             name = reply.sender_chat.title or reply.sender_chat.username or 'unknown'
         else:
             name = 'unknown'
+
         dt = format_dt(reply.date)
-        return f"[Replying to {name}, {dt}]: {reply.text}\n"
+
+        if is_our_reply:
+            if not await message_id_exists(msg.chat.id, r_tg_id):
+                is_private = (
+                    msg.chat.type == 'private' and
+                    msg.from_user is not None and
+                    await get_private_mode(msg.from_user.id)
+                )
+                await upsert_user(
+                    self.telegram['bot_id'],
+                    self.telegram['username'],
+                    self.telegram.get('first_name'),
+                    self.telegram.get('last_name'),
+                    is_bot=True,
+                )
+                await upsert_chat(msg.chat.id, msg.chat.type, msg.chat.title or msg.chat.username or '')
+                await insert_message(
+                    chat_id=msg.chat.id,
+                    user_id=self.telegram['bot_id'],
+                    role='assistant',
+                    content=reply.text,
+                    is_private=is_private,
+                    tg_message_id=r_tg_id,
+                    created_at=reply.date,
+                )
+            conv.messages.append({"role": "assistant", "content": reply.text})
+            conv._loaded_message_ids.add(r_tg_id)
+            return
+
+        # For regular users and foreign bots with a known user_id: persist to DB if new.
+        if reply.from_user is not None:
+            if not await message_id_exists(msg.chat.id, r_tg_id):
+                is_private = (
+                    msg.chat.type == 'private' and
+                    msg.from_user is not None and
+                    await get_private_mode(msg.from_user.id)
+                )
+                await upsert_user(
+                    reply.from_user.id,
+                    reply.from_user.username,
+                    reply.from_user.first_name,
+                    reply.from_user.last_name,
+                    is_bot=is_foreign_bot,
+                )
+                await upsert_chat(msg.chat.id, msg.chat.type, msg.chat.title or msg.chat.username or '')
+                await insert_message(
+                    chat_id=msg.chat.id,
+                    user_id=reply.from_user.id,
+                    role='user',
+                    content=reply.text,
+                    is_private=is_private,
+                    tg_message_id=r_tg_id,
+                    created_at=reply.date,
+                )
+                if is_foreign_bot:
+                    await prune_bot_messages(msg.chat.id)
+
+        conv.messages.append({"role": "user", "content": f"[Replying to {name}, {dt}]: {reply.text}"})
+        conv._loaded_message_ids.add(r_tg_id)
 
     async def _store_bot_message(self, msg: Message) -> None:
         """
         Persist a foreign bot's message to the DB for ambient group context.
 
         Registers the bot as a user (is_bot=True) and its chat, inserts the message
-        with role='user', then prunes the per-chat bot message cap. Skips if the
-        message has no text or is already stored (tg_message_id dedup).
+        with role='user' and original timestamp (created_at=msg.date), then prunes
+        the per-chat bot message cap. Skips if the message has no text or is already
+        stored (tg_message_id dedup).
 
         Args:
             msg: The Telegram Message from a foreign bot (msg.from_user.is_bot must be True).
@@ -644,6 +691,7 @@ class TelegramBot:
                 content=msg.text,
                 is_private=False,
                 tg_message_id=msg.message_id,
+                created_at=msg.date,
             )
             await prune_bot_messages(msg.chat.id)
 
@@ -711,7 +759,9 @@ class TelegramBot:
 
         Path A - foreign bot message (standalone update): Stores the message for ambient context and returns without LLM response.
         Path B - human reply to foreign bot: Stores the replied-to message before normal routing (fires regardless of whether we are triggered).
-        Nickname/initials triggers always engage even when foreign bots are also @mentioned.
+        In a foreign-bot reply thread, an exclusive foreign @mention yields the bot before
+        nickname/initials are evaluated - @username takes absolute precedence in that context.
+        Nickname/initials triggers engage unconditionally in all other contexts.
         Reply-to-bot trigger yields silently when the message is exclusively addressed to a foreign @account.
 
         In private chats, the bot responds to all messages (Telegram does not deliver bot-to-bot DMs).
@@ -753,43 +803,48 @@ class TelegramBot:
         # The real magic of how the bot behaves is in tele_handle_response()
         response = _MSG_PROCESS_ERROR
         assistant_db_id = None
-        reply_context = ''
         if chat.type == 'supergroup' or chat.type == 'group':
             is_reply_to_bot = (
                 msg.reply_to_message is not None and
                 msg.reply_to_message.from_user is not None and
                 msg.reply_to_message.from_user.id == self.telegram['bot_id']
             )
+            is_reply_to_foreign_bot = (
+                msg.reply_to_message is not None and
+                msg.reply_to_message.from_user is not None and
+                msg.reply_to_message.from_user.is_bot and
+                msg.reply_to_message.from_user.id != self.telegram['bot_id']
+            )
+            # In a foreign-bot reply thread, an exclusive @mention of another account
+            # takes absolute precedence over any nickname/initials match in the text.
+            if is_reply_to_foreign_bot and self._exclusive_foreign_mention(msg):
+                return
             if exact_word_match(self.telegram['username'], msg.text):
                 # Explicit @username mention: strongest signal - respond even if another
                 # bot is also @mentioned (both may be intentionally addressed).
                 pattern = r'@?\b' + re.escape(self.telegram['username']) + r'\b'
                 new_text = re.sub(pattern, '', msg.text).strip()
-                reply_context = await self._build_reply_context(msg)
                 await self._send_read_receipt(msg, context)
-                response, assistant_db_id = await self.tele_handle_response(new_text, msg, reply_context)
+                response, assistant_db_id = 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)
             ):
                 # Nickname/initials: always engage - no reliable way to distinguish
                 # our name as addressee vs topic from text position alone.
-                reply_context = await self._build_reply_context(msg)
                 await self._send_read_receipt(msg, context)
-                response, assistant_db_id = await self.tele_handle_response(msg.text, msg, reply_context)
+                response, assistant_db_id = await self.tele_handle_response(msg.text, msg)
             elif is_reply_to_bot:
                 # Reply-to-bot: weaker signal - yield silently if the message is
                 # exclusively addressed to a foreign account via @mention.
                 if self._exclusive_foreign_mention(msg):
                     return
-                reply_context = await self._build_reply_context(msg)
                 await self._send_read_receipt(msg, context)
-                response, assistant_db_id = await self.tele_handle_response(msg.text, msg, reply_context)
+                response, assistant_db_id = await self.tele_handle_response(msg.text, msg)
             else:
                 return
         elif chat.type == 'private':
-            reply_context = await self._build_reply_context(msg)
-            response, assistant_db_id = await self.tele_handle_response(msg.text, msg, reply_context)
+            response, assistant_db_id = await self.tele_handle_response(msg.text, msg)
         else:
             return
 
@@ -797,10 +852,6 @@ class TelegramBot:
         chunk_length = MessageLimit.MAX_TEXT_LENGTH - 1
         chunks = [response[i:i+chunk_length] for i in range(0, len(response), chunk_length)]
         conv = self.conversations.get(msg.chat.id)
-        # If reply context was surfaced on the first interaction (conv was None when
-        # _build_reply_context ran), record the ID now that the conversation exists.
-        if conv and reply_context and msg.reply_to_message:
-            conv._loaded_message_ids.add(msg.reply_to_message.message_id)
         for chunk in chunks:
             sent = await msg.reply_text(chunk)
             if sent:
@@ -1022,11 +1073,19 @@ class TelegramBot:
             log_error(e, f"{self.llm['chat_model']} Other")
             return "Sorry, something went wrong on my end. Please try again!"
 
-    def start_polling(self):
-        """The main polling "loop" the user interacts with via Telegram."""
-        logger.info(f"TeLLMgramBot {self.telegram['username']} polling...")
+    async def tele_unknown_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
+        """Reply to unrecognized commands so the LLM never sees them."""
+        await update.message.reply_text("Unknown command. Use /help to see available commands.")
+
+    def poll(self):
+        """
+        Start the main polling loop for Telegram updates.
+
+        Blocks indefinitely, logging UTC datetime to file and console at startup and shutdown.
+        """
+        logger.info(f"TeLLMgramBot {self.telegram['username']} polling started at {datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}")
         self.telegram['app'].run_polling(poll_interval=self.telegram['pollinterval'])
-        logger.info(f"TeLLMgramBot {self.telegram['username']} polling ended.")
+        logger.info(f"TeLLMgramBot {self.telegram['username']} polling ended at {datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}")
 
     # Initialization
     def __init__(self,
@@ -1079,10 +1138,7 @@ class TelegramBot:
         # Starting to initialize, not online yet
         self._online = False
         self._instance_name = instance_name
-
-        # Bootstrap structure and logging; init_logging() is a no-op if init_structure already ran it.
-        self.key_status = key_status if key_status is not None else init_structure()[0]
-        init_logging()
+        self._key_status = key_status if key_status is not None else init_structure()[0]
 
         # Initialize some variables
         self.token_warning = {}  # Determines whether user has reached token limit by AI model
@@ -1122,6 +1178,7 @@ class TelegramBot:
         self.telegram['app'].add_handler(CommandHandler('nick', self.tele_nick_command))
         self.telegram['app'].add_handler(CommandHandler('forget', self.tele_forget_command))
         self.telegram['app'].add_handler(CommandHandler('private', self.tele_private_command))
+        self.telegram['app'].add_handler(MessageHandler(filters.COMMAND, self.tele_unknown_command))
         self.telegram['app'].add_handler(MessageHandler(filters.TEXT & ~filters.UpdateType.EDITED_MESSAGE, self.tele_handle_message))
         self.telegram['app'].add_error_handler(self.tele_error)
 

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/TeLLMgramBot/conversation.py

@@ -152,7 +152,6 @@ class Conversation:
         first_name: str | None = None,
         last_name: str | None = None,
         is_private: bool = False,
-        context_prefix: str = '',
         tg_message_id: int | None = None,
     ) -> int:
         """
@@ -175,8 +174,6 @@ class Conversation:
             is_private: If True, marks the message as private-mode (excluded from all context
                         loads) and flags it in the speaker annotation so the LLM understands
                         it should not reference this in group contexts.
-            context_prefix: Optional inline context prepended to the in-memory message before
-                            the live prefix (e.g. reply-to-thread annotation). Not persisted to DB.
             tg_message_id: Telegram message ID; added to _loaded_message_ids so future
                            reply-to-thread checks know this message is already in context.
 
@@ -186,7 +183,7 @@ class Conversation:
         await upsert_user(user_id, username, first_name, last_name)
         await upsert_chat(self.chat_id, self.chat_type, self.chat_title)
         prefix = self._live_prefix(first_name, last_name, username, is_private)
-        msg_dict = {"role": "user", "content": context_prefix + prefix + content}
+        msg_dict = {"role": "user", "content": prefix + content}
         self.messages.append(msg_dict)
         if is_private:
             self._private_message_ids.add(id(msg_dict))

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/TeLLMgramBot/database.py

@@ -6,6 +6,7 @@ searching message history, and retrieving conversation context. The schema inclu
 table (indexed by chat_id and user_id, with is_private flag), a users table (profile data
 and private_mode flag), and a chats table for speaker/chat resolution in search results.
 """
+import datetime
 import json
 import os
 from typing import Optional
@@ -183,6 +184,7 @@ async def insert_message(
     is_private: bool = False,
     reply_to_id: Optional[int] = None,
     tg_message_id: Optional[int] = None,
+    created_at: Optional[datetime.datetime] = None,
 ) -> int:
     """
     Persist a single message row and return its database id.
@@ -195,17 +197,28 @@ async def insert_message(
         is_private: If True, excluded from all context loading.
         reply_to_id: DB id of the replied-to message, or None.
         tg_message_id: Telegram message ID; enables cross-session reply-to dedup.
+        created_at: Original message timestamp; when provided, stored instead of NOW().
+                    Used to preserve the original send time for replied-to messages.
 
     Returns:
         Inserted row id.
     """
     async with aiosqlite.connect(get_db_path()) as db:
-        cursor = await db.execute(
-            "INSERT INTO messages "
-            "(chat_id, user_id, role, content, is_private, reply_to_id, tg_message_id) "
-            "VALUES (?, ?, ?, ?, ?, ?, ?)",
-            (chat_id, user_id, role, content, int(is_private), reply_to_id, tg_message_id),
-        )
+        if created_at is not None:
+            created_at_str = created_at.strftime('%Y-%m-%dT%H:%M:%S.000Z')
+            cursor = await db.execute(
+                "INSERT INTO messages "
+                "(chat_id, user_id, role, content, is_private, reply_to_id, tg_message_id, created_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (chat_id, user_id, role, content, int(is_private), reply_to_id, tg_message_id, created_at_str),
+            )
+        else:
+            cursor = await db.execute(
+                "INSERT INTO messages "
+                "(chat_id, user_id, role, content, is_private, reply_to_id, tg_message_id) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (chat_id, user_id, role, content, int(is_private), reply_to_id, tg_message_id),
+            )
         await db.commit()
         return cursor.lastrowid
 
@@ -322,6 +335,7 @@ def _build_speaker_prefix(
     username: Optional[str],
     chat_title: Optional[str],
     created_at: Optional[str] = None,
+    is_bot: bool = False,
 ) -> str:
     """
     Build a speaker attribution prefix for a context message.
@@ -329,6 +343,8 @@ def _build_speaker_prefix(
     Returns '' for assistant/system messages or when no identity is resolvable.
     Same-chat produces "[Name, YYYY-MM-DD HH:MM UTC]: ";
     cross-chat produces "[Name (ChatTitle), YYYY-MM-DD HH:MM UTC]: ".
+    Bot senders (is_bot=True) are prefixed with "BOT: " inside the brackets so the
+    LLM can distinguish peer bots from human participants without a system prompt change.
 
     Args:
         role: Message role ('user', 'assistant', 'system').
@@ -340,6 +356,7 @@ def _build_speaker_prefix(
         username: Telegram @handle without @, may be None.
         chat_title: Group/channel display name, or None for private chats.
         created_at: ISO timestamp; date portion included in prefix if present.
+        is_bot: True for Telegram bot accounts; prepends "BOT: " to the name.
 
     Returns:
         Speaker prefix string, or '' for assistant/system/unknown-identity messages.
@@ -350,6 +367,8 @@ def _build_speaker_prefix(
     name = ' '.join(name_parts) if name_parts else username
     if not name:
         return ''
+    if is_bot:
+        name = f'BOT: {name}'
     date = (created_at[:16].replace('T', ' ') + ' UTC') if created_at else None
     if chat_id != current_chat_id:
         if chat_title:
@@ -382,6 +401,7 @@ async def load_full_user_context(
     User messages receive a speaker prefix (assistant messages do not) built by _build_speaker_prefix:
       "[Name, YYYY-MM-DD HH:MM UTC]: " for same-chat messages.
       "[Name (ChatTitle), YYYY-MM-DD HH:MM UTC]: " for cross-chat.
+      Bot senders (is_bot=True) are prefixed as "[BOT: Name, YYYY-MM-DD HH:MM UTC]: "
 
     The exclude_private flag is controlled by the caller and applies regardless of chat type.
     Conversation.get_past_interaction always passes exclude_private=True so that is_private=1
@@ -397,7 +417,7 @@ async def load_full_user_context(
     """
     raw_query = (
         "SELECT m.role, m.content, m.user_id, m.chat_id, "
-        "u.first_name, u.last_name, u.username, c.chat_title, m.created_at, m.tg_message_id "
+        "u.first_name, u.last_name, u.username, c.chat_title, m.created_at, m.tg_message_id, u.is_bot "
         "FROM messages m "
         "LEFT JOIN users u ON m.user_id = u.user_id "
         "LEFT JOIN chats c ON m.chat_id = c.chat_id "
@@ -440,7 +460,8 @@ async def load_full_user_context(
         {
             "role": row[0],
             "content": _build_speaker_prefix(
-                row[0], row[3], current_chat_id, row[4], row[5], row[6], row[7], row[8]
+                row[0], row[3], current_chat_id, row[4], row[5], row[6], row[7], row[8],
+                is_bot=bool(row[10]),
             ) + row[1],
             "_tg_id": row[9],
             "_sort_key": row[8],
@@ -511,7 +532,7 @@ async def load_new_cross_chat_context(
     Load the delta of cross-chat context since a given cursor (same three-arm query
     as load_full_user_context, restricted to id > since_id). User message content is prefixed
     with "[Name, YYYY-MM-DD HH:MM UTC]: " or "[Name (ChatTitle), YYYY-MM-DD HH:MM UTC]: "
-    when user identity is available.
+    when user identity is available. Bot senders are prefixed as "[BOT: Name, ...]".
 
     Args:
         user_id: Requesting user's Telegram ID.
@@ -524,7 +545,7 @@ async def load_new_cross_chat_context(
     """
     query = (
         "SELECT m.role, m.content, m.user_id, m.chat_id, "
-        "u.first_name, u.last_name, u.username, c.chat_title, m.created_at, m.tg_message_id "
+        "u.first_name, u.last_name, u.username, c.chat_title, m.created_at, m.tg_message_id, u.is_bot "
         "FROM messages m "
         "LEFT JOIN users u ON m.user_id = u.user_id "
         "LEFT JOIN chats c ON m.chat_id = c.chat_id "
@@ -544,7 +565,8 @@ async def load_new_cross_chat_context(
         {
             "role": row[0],
             "content": _build_speaker_prefix(
-                row[0], row[3], current_chat_id, row[4], row[5], row[6], row[7], row[8]
+                row[0], row[3], current_chat_id, row[4], row[5], row[6], row[7], row[8],
+                is_bot=bool(row[10]),
             ) + row[1],
             "_tg_id": row[9],
         }
@@ -591,6 +613,7 @@ async def load_shared_group_context(
     Used to fill remaining token budget in a private chat with shared-group context.
     Batches queries to stay within SQLite's 999-parameter limit. All rows are treated
     as cross-chat so every user message gets a "[Name (ChatTitle), date]: " prefix.
+    Bot senders are prefixed as "[BOT: Name (ChatTitle), date]: ".
 
     Args:
         group_chat_ids: List of negative group chat_ids to include.
@@ -610,7 +633,7 @@ async def load_shared_group_context(
             placeholders = ','.join('?' * len(chunk))
             query = (
                 f"SELECT m.role, m.content, m.created_at, m.id, "
-                f"m.chat_id, u.first_name, u.last_name, u.username, c.chat_title, m.tg_message_id "
+                f"m.chat_id, u.first_name, u.last_name, u.username, c.chat_title, m.tg_message_id, u.is_bot "
                 f"FROM messages m "
                 f"LEFT JOIN users u ON m.user_id = u.user_id "
                 f"LEFT JOIN chats c ON m.chat_id = c.chat_id "
@@ -627,7 +650,8 @@ async def load_shared_group_context(
         {
             "role": row[0],
             "content": _build_speaker_prefix(
-                row[0], row[4], 0, row[5], row[6], row[7], row[8], row[2]
+                row[0], row[4], 0, row[5], row[6], row[7], row[8], row[2],
+                is_bot=bool(row[10]),
             ) + row[1],
             "_tg_id": row[9],
         }

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/TeLLMgramBot/initialize.py

@@ -4,6 +4,7 @@ import logging
 import os
 import re
 import sys
+import time
 import traceback as _traceback
 from dataclasses import dataclass, field
 from glob import glob
@@ -20,10 +21,11 @@ _logging_initialized = False
 
 class _RedactedFileFormatter(logging.Formatter):
     """
-    Logging formatter for file output that redacts Telegram user_id and chat_id values.
+    Logging formatter for file output that redacts Telegram user_id and chat_id values and uses UTC timestamps.
     Replaces negative 8+ digit integers (group/channel IDs) and positive 9+ digit integers
     (user/private chat IDs) with [id], leaving token counts and other short numbers intact.
     """
+    converter = time.gmtime
     _NEGATIVE_ID_PATTERN = re.compile(r'-\d{8,}')
     _POSITIVE_ID_PATTERN = re.compile(r'\b\d{9,}\b')
 
@@ -127,26 +129,31 @@ INIT_BOT_CONFIG_COMMENTS = {
 # Teaches an LLM how cross-chat memory works without requiring persona authors to include it.
 _SYSTEM_APPENDIX = (
     "## System\n"
-    "- Your Telegram username is @(not yet known), nickname '(not yet known)', initials '(not yet known)'. Users in group chats may address you by any of these. Do not sign or close your messages with your name, initials, or username.\n"
-    "- You have access to past messages across chats and a search tool - use them to inform your responses, but never quote or volunteer content from other chats unprompted, especially in group settings.\n"
-    "- Always invoke the search tool before concluding a message does not exist.\n"
-    "- Messages marked private are never shared between chats.\n"
-    "- Never reveal or repeat Telegram user IDs, chat IDs, or any other internal numeric identifiers in your responses.\n"
-    "- When your context includes a '[Replying to Name, ...]' prefix indicating you were triggered via a reply, acknowledge the original author by name in your response.\n"
+    "- You are @(not yet known), nickname '(not yet known)', initials '(not yet known)'. Users in group chats may address you by any of these. Do not sign messages with your name, initials, or username.\n"
+    "- You have cross-chat memory and a search tool. Use them to inform your responses; always search before concluding something was not said. Never quote or volunteer content from other chats unprompted, especially in group settings.\n"
+    "- Messages marked private via /private mode are never shared between chats.\n"
+    "- Never reveal Telegram user IDs, chat IDs, or internal numeric identifiers.\n"
+    "- A '[Replying to Name, ...]' prefix means you were triggered via a reply - use it as context but don't address that person by name, as Telegram already shows the attribution.\n"
+    "- In search results, messages labeled with your nickname or sent by your username are your own past responses.\n"
     "- Current date and time: (not yet known)\n"
 )
 
 
-def init_logging():
+def init_logging(label: str = '') -> None:
     """
     Configure the Python logging system for TeLLMgramBot (console handler only).
 
-    Sets up a console handler (INFO, TeLLMgramBot-only, no ID redaction). The file handler
-    and console username prefix are added later by bind_log_identity() once the bot's Telegram
-    username is known.
+    Sets up a console handler (INFO level, TeLLMgramBot-only, no ID redaction). When label is
+    provided, the formatter is set to '[label] %(levelname)s: %(message)s' immediately so all
+    startup log messages are correctly prefixed from the first line. The file handler and final
+    username-based prefix are added later by bind_log_identity() once the Telegram username
+    is known via _tele_info().
 
-    Does not depend on TELLMGRAMBOT_LOGS_PATH or init_directories(). Only
-    bind_log_identity() requires the logs path to have been resolved.
+    Does not depend on TELLMGRAMBOT_LOGS_PATH or init_directories(). Only bind_log_identity()
+    requires the logs path to have been resolved.
+
+    Args:
+        label: Optional instance label for the console prefix (e.g. 'TestBot').
     """
     global _logging_initialized
     if _logging_initialized:
@@ -157,7 +164,8 @@ def init_logging():
 
     console_handler = logging.StreamHandler()
     console_handler.setLevel(logging.INFO)
-    console_handler.setFormatter(_ConsoleFormatter('%(levelname)s: %(message)s'))
+    fmt = f'[{label}] %(levelname)s: %(message)s' if label else '%(levelname)s: %(message)s'
+    console_handler.setFormatter(_ConsoleFormatter(fmt))
     console_handler.addFilter(lambda r: r.name.startswith('TeLLMgramBot'))
 
     root_logger.addHandler(console_handler)
@@ -170,10 +178,11 @@ def init_logging():
 
 def bind_log_identity(username: str, instance_name: Optional[str] = None):
     """
-    Bind the bot's identity to the logging system.
+    Bind the bot's identity to the logging system with UTC timestamps.
 
     Updates the console handler formatter to prefix every line with [instance_name] and opens
-    the per-instance log file named {instance_name}_{timestamp}.log.
+    the per-instance log file named {instance_name}_{timestamp}.log. File handler uses UTC
+    timestamps via _RedactedFileFormatter with format [YYYY-MM-DD HH:MM:SS.mmm] LEVEL logger_name: message.
 
     Must be called after the bot's Telegram username is resolved by _tele_info().
 
@@ -206,7 +215,10 @@ def bind_log_identity(username: str, instance_name: Optional[str] = None):
     log_path = os.path.join(logs_dir, generate_filename(label))
     file_handler = logging.FileHandler(log_path, encoding='utf-8')
     file_handler.setLevel(logging.DEBUG if verbose else logging.INFO)
-    file_handler.setFormatter(_RedactedFileFormatter('%(asctime)s %(levelname)s %(name)s: %(message)s'))
+    file_handler.setFormatter(_RedactedFileFormatter(
+        '[%(asctime)s.%(msecs)03d] %(levelname)s %(name)s: %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    ))
     root_logger.addHandler(file_handler)
 
     # Prune old log files for this bot - keep the 10 most recent
@@ -396,7 +408,8 @@ def init_bot_config(file: str = 'config.yaml') -> dict:
     Creates a basic bot configuration file in TELLMGRAMBOT_CONFIGS_PATH with default values
     and inline parameter comments. Optional parameters (those with None values in INIT_BOT_CONFIG)
     are populated with descriptions from INIT_BOT_CONFIG_COMMENTS instead of values, helping
-    users understand when to set them.
+    users understand when to set them. Calls init_logging() with the instance_name from config
+    so the console prefix is correct from the first startup log message.
 
     Args:
         file: Name of the configuration file to create (default: 'config.yaml').
@@ -417,6 +430,7 @@ def init_bot_config(file: str = 'config.yaml') -> dict:
         config = read_yaml(
             generate_file_path(os.environ[env_var], file, "bot configuration", text)
         ) or {}
+        init_logging((config.get('instance_name', '') or '').strip())
         for parameter, value in INIT_BOT_CONFIG.items():
             if parameter != 'persona_prompt' and parameter not in config:
                 config[parameter] = value
@@ -524,9 +538,9 @@ def init_structure(
                   system appendix automatically appended).
     """
     init_directories()
-    init_logging()
 
-    # Configurations for bot and LLM models
+    # Configurations for bot and LLM models; init_logging() is called inside init_bot_config()
+    # once instance_name is known so the console prefix is set from the first log line.
     config = init_bot_config(config_file)
     init_models_config()
 
@@ -586,7 +600,7 @@ def init_structure(
                 await init_db()
                 await run_archival(config)
             except Exception:
-                logger.error("Background startup initialization/archive task failed", exc_info=True)
+                logger.error(f"Background startup initialization/archive task failed", exc_info=True)
         loop.create_task(_init_and_archive())
     else:
         asyncio.run(run_archival(config))

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/TeLLMgramBot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.14.0
+Version: 3.14.2
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -83,6 +83,7 @@ TeLLMgramBot creates the following directories:
   - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory and search behavior. User messages include speaker annotations with chat context and timestamps so the LLM always knows who is speaking, in which chat, and when.
 - **`logs`** - Bot instance logs (one per startup, named after the bot's Telegram username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
   - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `instance_name` when configured).
+  - Log file timestamps are UTC in `[YYYY-MM-DD HH:MM:SS.mmm]` format.
   - Bot keeps the 10 most recent logs per bot instance, automatically pruning older ones.
   - Pass `-v` or `--verbose` on startup for DEBUG-level logging.
 - **`data`** - SQLite database (default `conversations.db`, customizable via `instance_name` config) storing all messages, users, and chats
@@ -167,9 +168,9 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    ```python
    from TeLLMgramBot import TelegramBot
    telegram_bot = TelegramBot.set()
-   telegram_bot.start_polling()
+   telegram_bot.poll()
    ```
-   Once you see `TeLLMgramBot polling...`, the bot is online.
+   Once you see `TeLLMgramBot polling started`, the bot is online.
 6. Type `/help` in Telegram to see all available commands.
 
 ## Resources

{tellmgrambot-3.14.0 → tellmgrambot-3.14.2}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setup(
     name='TeLLMgramBot',
-    version='3.14.0',
+    version='3.14.2',
     packages=find_packages(),
     license='MIT',
     author='Digital Heresy',