TeLLMgramBot 3.15.2__tar.gz → 3.15.4__tar.gz

{tellmgrambot-3.15.2 → tellmgrambot-3.15.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.15.2
+Version: 3.15.4
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -168,6 +168,7 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). Older messages are distilled into daily summaries, then progressively compressed into monthly digests. Once archived their respective raw messages do not return to the LLM context any more, only when searching messages.
    - `document_processing`: Optional bool (default: true). Set to false to disable document and text file summarisation.
    - `allow_local_webhooks`: Set to `true` to permit webhook/MCP URLs targeting loopback or link-local addresses (optional; default `false`). Useful when tools like Home Assistant run on the same host.
+   - `max_conversations`: Optional max chats kept in memory at once (default: 500, minimum 1). Least-recently-used chats beyond this cap are evicted and reload from the database on their next message. Useful for deployments with memory constraints; evicted chats retain all persisted data.
    - `tools`: Optional list of webhook and MCP tool definitions (admin-only, private chat only). See [docs/tools.md](docs/tools.md) for schema and examples.
 4. **Disable group privacy mode in BotFather:**
    ```

{tellmgrambot-3.15.2 → tellmgrambot-3.15.4}/README.md

@@ -131,6 +131,7 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). Older messages are distilled into daily summaries, then progressively compressed into monthly digests. Once archived their respective raw messages do not return to the LLM context any more, only when searching messages.
    - `document_processing`: Optional bool (default: true). Set to false to disable document and text file summarisation.
    - `allow_local_webhooks`: Set to `true` to permit webhook/MCP URLs targeting loopback or link-local addresses (optional; default `false`). Useful when tools like Home Assistant run on the same host.
+   - `max_conversations`: Optional max chats kept in memory at once (default: 500, minimum 1). Least-recently-used chats beyond this cap are evicted and reload from the database on their next message. Useful for deployments with memory constraints; evicted chats retain all persisted data.
    - `tools`: Optional list of webhook and MCP tool definitions (admin-only, private chat only). See [docs/tools.md](docs/tools.md) for schema and examples.
 4. **Disable group privacy mode in BotFather:**
    ```

{tellmgrambot-3.15.2 → tellmgrambot-3.15.4}/TeLLMgramBot/TeLLMgramBot.py

@@ -5,6 +5,7 @@ import logging
 import json
 import os
 import re
+from collections import OrderedDict
 from math import floor
 
 from telegram import Bot, Update, Message, Chat, User, ReactionTypeEmoji, MessageEntity, InlineKeyboardButton, InlineKeyboardMarkup
@@ -79,6 +80,23 @@ def _validated_allow_local(value) -> bool:
     return value is True
 
 
+def _validated_max_conversations(value) -> int:
+    """
+    Validate the max_conversations config value, defaulting to 500 on invalid input.
+
+    Caps how many Conversation objects self.conversations keeps in memory at once;
+    least-recently-used chats beyond this cap are evicted and reload from DB on
+    their next message.
+
+    Args:
+        value: Raw `max_conversations` value from bot config.
+    """
+    if value is not None and not (type(value) is int and value >= 1):
+        logger.warning(f"Invalid max_conversations '{value}' (must be an integer >= 1); using default 500")
+        return 500
+    return value if value is not None else 500
+
+
 _SEARCH_TOOL = {
     "name": "search_messages",
     "description": (
@@ -438,6 +456,12 @@ class TelegramBot:
         session (get_past_interaction) or checks for new messages since the last load
         (refresh_user_context).
 
+        self.conversations is an OrderedDict capped at self.llm['max_conversations'] entries.
+        Every call moves chat_id to the most-recently-used end; inserting past the cap evicts
+        the least-recently-used chat (and its token_warning entry) from memory. Eviction never
+        deletes persisted data - an evicted chat's next message cold-loads from DB exactly like
+        a chat the bot has never seen before.
+
         Args:
             chat_id: Telegram chat ID.
             chat_type: 'private', 'group', or 'supergroup'.
@@ -447,10 +471,15 @@ class TelegramBot:
         Returns:
             The active Conversation for this chat.
         """
-        if chat_id not in self.conversations:
+        if chat_id in self.conversations:
+            self.conversations.move_to_end(chat_id)
+        else:
             self.conversations[chat_id] = Conversation(
                 chat_id, chat_type, self.llm['prompt'], self.llm['chat_model'], chat_title,
             )
+            if len(self.conversations) > self.llm['max_conversations']:
+                evicted_id, _ = self.conversations.popitem(last=False)
+                self.token_warning.pop(evicted_id, None)
         conv = self.conversations[chat_id]
         conv.update_datetime()
 
@@ -1250,12 +1279,60 @@ class TelegramBot:
 
         Registered as python-telegram-bot's post_init hook so a large archival backlog or slow/unreachable MCP
         servers never block tele_handle_message/tele_handle_document from answering the first incoming update.
-        Uses application.create_task() rather than asyncio.create_task() so both tasks are tracked and
-        cancelled cleanly on shutdown.
+
+        Schedules both tasks via _schedule_background_task(), which wraps asyncio.create_task()
+        directly. PTB's own Application.create_task() only tracks a task for graceful shutdown
+        once application.running is True; post_init runs before Application.start() sets that
+        flag, so scheduling through Application.create_task() here would go untracked anyway and
+        emit a PTBUserWarning. Task references are kept in self._background_tasks until each task
+        completes, since asyncio does not hold a strong reference to a task on your behalf.
         """
         if self._mcp_entries:
-            application.create_task(self._discover_mcp_tools_background())
-        application.create_task(run_archival(self.llm))
+            self._schedule_background_task(self._discover_mcp_tools_background())
+        self._schedule_background_task(run_archival(self.llm))
+
+    def _schedule_background_task(self, coro) -> asyncio.Task:
+        """
+        Run coro as a fire-and-forget asyncio task, keeping a reference until it completes.
+
+        asyncio does not keep a strong reference to a task once its creator's local
+        variable goes out of scope, so a task can be garbage-collected mid-execution
+        without this. The done-callback removes the task from self._background_tasks
+        and retrieves any exception via _on_background_task_done(), so an unhandled
+        failure surfaces through our own logging instead of asyncio's "Task exception
+        was never retrieved" warning on garbage collection.
+
+        Args:
+            coro: The coroutine to schedule.
+
+        Returns:
+            The created asyncio.Task.
+        """
+        task = asyncio.create_task(coro)
+        self._background_tasks.add(task)
+        task.add_done_callback(self._on_background_task_done)
+        return task
+
+    def _on_background_task_done(self, task: asyncio.Task) -> None:
+        """
+        Done-callback for _schedule_background_task(): discard the reference and log
+        any unhandled exception.
+
+        Retrieving the exception here (rather than leaving it unread) prevents asyncio's
+        default exception handler from emitting "Task exception was never retrieved" when
+        the task is garbage-collected. A cancelled task has no exception to retrieve -
+        task.exception() raises CancelledError in that case, so cancellation is checked
+        first and treated as a normal, silent outcome.
+
+        Args:
+            task: The completed (or cancelled) background task.
+        """
+        self._background_tasks.discard(task)
+        if task.cancelled():
+            return
+        exc = task.exception()
+        if exc is not None:
+            log_error(exc, 'BackgroundTask')
 
     async def _discover_mcp_tools_background(self) -> None:
         """
@@ -1298,6 +1375,7 @@ class TelegramBot:
         persona_temp        = INIT_BOT_CONFIG['persona_temp'],
         archive_days        = INIT_BOT_CONFIG['archive_days'],
         document_processing = INIT_BOT_CONFIG['document_processing'],
+        max_conversations   = INIT_BOT_CONFIG['max_conversations'],
         persona_prompt      = INIT_BOT_CONFIG['persona_prompt'],
         key_status: ApiKeyStatus | None = None,
         instance_name: str | None = None,
@@ -1326,6 +1404,9 @@ class TelegramBot:
             archive_days: Days before messages are eligible for Tier 1 archival (default: 60).
                           Must be an integer >= 1; invalid values log a warning and fall back to 60.
                           Tier 2 compression triggers at archive_days * 2.
+            max_conversations: Max chats kept in self.conversations at once (default: 500).
+                               Validated by _validated_max_conversations(); least-recently-used
+                               chats beyond this cap are evicted in _get_or_load_conversation().
             webhook_schemas: Provider-compatible tool schema dicts for webhook tools (from build_tool_registry).
                              If None, no webhook tools are registered.
             webhook_defs: Resolved webhook tool definitions keyed by tool name (from build_tool_registry).
@@ -1348,11 +1429,14 @@ class TelegramBot:
 
         # Initialize some variables
         self.token_warning = {}  # Determines whether user has reached token limit by AI model
-        self.conversations = {}  # Provides Conversation class per user based on bot response
+        # Provides Conversation class per chat_id; an OrderedDict so _get_or_load_conversation()
+        # can track recency via move_to_end() and evict the least-recently-used entry on overflow.
+        self.conversations: OrderedDict = OrderedDict()
         self.webhook_schemas = webhook_schemas or []  # Provider-compatible schemas for webhook tools
         self.webhook_defs = webhook_defs or {}  # Resolved tool definitions keyed by name
         self._mcp_entries = mcp_entries or []  # Raw mcp_server entries; discovered in _post_init()
         self._allow_local_webhooks = allow_local_webhooks
+        self._background_tasks: set = set()  # Keeps fire-and-forget tasks referenced until done
         owners = bot_owner if isinstance(bot_owner, list) else [bot_owner]
         self.telegram = {
             'bot_id'       : 0,  # overwritten by _tele_info(); 0 is a safe sentinel
@@ -1366,13 +1450,14 @@ class TelegramBot:
         }
         # Check for event running loops before getting the bot's information
         try:
-            loop = asyncio.get_running_loop()
+            asyncio.get_running_loop()
         except RuntimeError:
             # No running event loop; safe to run synchronously
             asyncio.run(self._tele_info())
         else:
-            # Already in an event loop; schedule as a background task
-            loop.create_task(self._tele_info())
+            # Already in an event loop; schedule as a background task, keeping a
+            # reference via self._background_tasks so it isn't garbage-collected mid-run
+            self._schedule_background_task(self._tele_info())
 
         # Build our application with handlers for Commands, Messages, and Errors
         self.telegram['app'] = (
@@ -1422,6 +1507,7 @@ class TelegramBot:
             'top_p'               : 0.9,
             'archive_days'        : archive_days if archive_days is not None else 60,
             'document_processing' : document_processing if document_processing is not None else True,
+            'max_conversations'   : _validated_max_conversations(max_conversations),
         }
         # Set a rounded-down integer to prune a lengthy conversation by 500 tokens
         # Note if the upper limit is below 500, the lower limit is set to 0
@@ -1499,6 +1585,7 @@ class TelegramBot:
             persona_temp         = config['persona_temp'],
             archive_days         = config['archive_days'],
             document_processing  = config['document_processing'],
+            max_conversations    = config['max_conversations'],
             persona_prompt       = prompt,
             key_status           = key_status,
             instance_name        = config['instance_name'],

{tellmgrambot-3.15.2 → tellmgrambot-3.15.4}/TeLLMgramBot/initialize.py

@@ -113,6 +113,7 @@ INIT_BOT_CONFIG = {
     'archive_days': None,
     'allow_local_webhooks': None,
     'document_processing': None,
+    'max_conversations': None,
     'persona_prompt': 'You are a generic test bot powered by a user-configured LLM.'
 }
 
@@ -124,6 +125,7 @@ INIT_BOT_CONFIG_COMMENTS = {
     'archive_days': '# Optional, days before messages are eligible for Tier 1 archival (default: 60, min: 1). Tier 2 triggers at 2x this value.',
     'allow_local_webhooks': '# Optional, set to true to permit webhook/MCP URLs targeting loopback or link-local addresses (default: false)',
     'document_processing': '# Optional, set to false to disable document summarisation (default: true)',
+    'max_conversations': '# Optional, max chats kept in memory at once; least-recently-used chats beyond this cap are evicted and reload from DB on their next message (default: 500, min: 1)',
 }
 
 # Append the framework-owned system appendix to the persona prompt.

{tellmgrambot-3.15.2 → tellmgrambot-3.15.4}/TeLLMgramBot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.15.2
+Version: 3.15.4
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -168,6 +168,7 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). Older messages are distilled into daily summaries, then progressively compressed into monthly digests. Once archived their respective raw messages do not return to the LLM context any more, only when searching messages.
    - `document_processing`: Optional bool (default: true). Set to false to disable document and text file summarisation.
    - `allow_local_webhooks`: Set to `true` to permit webhook/MCP URLs targeting loopback or link-local addresses (optional; default `false`). Useful when tools like Home Assistant run on the same host.
+   - `max_conversations`: Optional max chats kept in memory at once (default: 500, minimum 1). Least-recently-used chats beyond this cap are evicted and reload from the database on their next message. Useful for deployments with memory constraints; evicted chats retain all persisted data.
    - `tools`: Optional list of webhook and MCP tool definitions (admin-only, private chat only). See [docs/tools.md](docs/tools.md) for schema and examples.
 4. **Disable group privacy mode in BotFather:**
    ```

{tellmgrambot-3.15.2 → tellmgrambot-3.15.4}/setup.py

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