TeLLMgramBot 3.10.4__tar.gz → 3.11.0__tar.gz

{tellmgrambot-3.10.4 → tellmgrambot-3.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.10.4
+Version: 3.11.0
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -122,9 +122,10 @@ os.environ['TELLMGRAMBOT_VIRUSTOTAL_API_KEY'] = my_vault.get('virustotal_key')
 
 ### Available Commands
 - `/nick <name>` - Set your nickname (for bot use in group chats).
-- `/forget` - Clear your conversation history. In private chats, clears everything and resets all active sessions. In group chats, removes only your messages.
+- `/forget` - Clear your conversation history. Shows a confirmation prompt before deletion. In private chats, clears everything and resets all active sessions. In group chats, removes only your messages.
 - `/private` - Toggle private mode (private chats only). When ON, your messages are excluded from group context loading.
-- `/help` - Display available commands and usage information. In private chats, if you are a bot owner, also shows administrator-only commands (`/start`, `/stop`, `/wipe`).
+- `/tools` - List all registered tools available to this bot instance (admin-only, private chat only). Shows the built-in search_messages tool and any webhook tools defined in config.yaml.
+- `/help` - Display available commands and usage information. In private chats, if you are a bot owner, also shows administrator-only commands (`/start`, `/stop`, `/wipe`, `/tools`).
 
 ### Group Chat Triggers
 The bot responds in groups when you:
@@ -151,6 +152,7 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `db_name`: Optional custom database filename without extension (e.g. `MyBot` creates `MyBot.db`); omit for default `conversations.db`. Use distinct names when running multiple bot instances in the same directory.
    - `token_limit`: Max tokens (optional; defaults to model's maximum)
    - `search_limit`: Max search results (optional; defaults to 30)
+   - `tools`: Optional list of webhook 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:**
    ```
    /setprivacy -> select your bot -> Disable

{tellmgrambot-3.10.4 → tellmgrambot-3.11.0}/README.md

@@ -90,9 +90,10 @@ os.environ['TELLMGRAMBOT_VIRUSTOTAL_API_KEY'] = my_vault.get('virustotal_key')
 
 ### Available Commands
 - `/nick <name>` - Set your nickname (for bot use in group chats).
-- `/forget` - Clear your conversation history. In private chats, clears everything and resets all active sessions. In group chats, removes only your messages.
+- `/forget` - Clear your conversation history. Shows a confirmation prompt before deletion. In private chats, clears everything and resets all active sessions. In group chats, removes only your messages.
 - `/private` - Toggle private mode (private chats only). When ON, your messages are excluded from group context loading.
-- `/help` - Display available commands and usage information. In private chats, if you are a bot owner, also shows administrator-only commands (`/start`, `/stop`, `/wipe`).
+- `/tools` - List all registered tools available to this bot instance (admin-only, private chat only). Shows the built-in search_messages tool and any webhook tools defined in config.yaml.
+- `/help` - Display available commands and usage information. In private chats, if you are a bot owner, also shows administrator-only commands (`/start`, `/stop`, `/wipe`, `/tools`).
 
 ### Group Chat Triggers
 The bot responds in groups when you:
@@ -119,6 +120,7 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `db_name`: Optional custom database filename without extension (e.g. `MyBot` creates `MyBot.db`); omit for default `conversations.db`. Use distinct names when running multiple bot instances in the same directory.
    - `token_limit`: Max tokens (optional; defaults to model's maximum)
    - `search_limit`: Max search results (optional; defaults to 30)
+   - `tools`: Optional list of webhook 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:**
    ```
    /setprivacy -> select your bot -> Disable

{tellmgrambot-3.10.4 → tellmgrambot-3.11.0}/TeLLMgramBot/TeLLMgramBot.py

@@ -7,10 +7,10 @@ import os
 import re
 from math import floor
 
-from telegram import Bot, Update, Message, Chat, User, ReactionTypeEmoji, MessageEntity
+from telegram import Bot, Update, Message, Chat, User, ReactionTypeEmoji, MessageEntity, InlineKeyboardButton, InlineKeyboardMarkup
 from telegram.constants import MessageLimit
 from telegram.error import TelegramError
-from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes
+from telegram.ext import Application, CallbackQueryHandler, CommandHandler, MessageHandler, filters, ContextTypes
 
 from .conversation import Conversation
 from .utils import format_dt
@@ -38,12 +38,25 @@ from .initialize import (
 )
 from .message_handlers import handle_greetings, handle_common_queries, handle_url_ask
 from .models import TokenLimits
+from .tools import build_tool_registry, execute_webhook
 from .providers.factory import get_provider
 from .providers.base import ContextLengthExceededError, ProviderAuthError, ProviderConnectionError, ToolCall
 from .utils import exact_word_match, log_error
 
 logger = logging.getLogger(__name__)
 
+# Dialog copy - centralised so tests never hard-code these strings
+_MSG_ADMIN_ONLY        = "Sorry, I can't do that for you."
+_MSG_PROCESS_ERROR     = "Sorry, I couldn't process your message! Please contact my creator."
+_MSG_TOOL_RESULT_ERROR = "Sorry, I couldn't process the tool result."
+_MSG_NOT_YOUR_PROMPT   = "Sorry, this prompt is not for you!"
+_MSG_WIPE_PROMPT       = "ALL of my memories will be lost! Are you sure?"
+_MSG_WIPE_COMPLETE     = "Wipe complete. I hope you won't regret this..."
+_MSG_WIPE_CANCELLED    = "Wipe cancelled. Whew, you scared me for a moment!"
+_MSG_FORGET_PROMPT     = "Do you really want me to forget our memories together?"
+_MSG_FORGET_COMPLETE   = "Forget complete. Fresh start it is..."
+_MSG_FORGET_CANCELLED  = "Forget cancelled. Glad you changed your mind!"
+
 _SEARCH_TOOL = {
     "name": "search_messages",
     "description": (
@@ -116,7 +129,8 @@ class TelegramBot:
                 "\n\nAdmin commands:\n"
                 "/start - Go online to receive new responses (default).\n"
                 "/stop - Go offline to prevent new responses.\n"
-                "/wipe - Permanently delete all conversation data (irreversible)."
+                "/wipe - Permanently delete all conversation data.\n"
+                "/tools - List all registered tools available to this bot."
             )
         await update.message.reply_text(text)
 
@@ -124,9 +138,8 @@ class TelegramBot:
         """
         Start the bot and resume handling new messages (admin-only).
 
-        Only usernames in self.telegram['owners'] can execute this command.
+        Only usernames in self.telegram['owners'] can execute this command; otherwise deny access.
         If the sender is an owner, sets self._online to True and confirms via reply.
-        Otherwise, denies access with "Sorry, I can't do that for you."
 
         Args:
             update: Telegram Update object containing the /start message.
@@ -138,15 +151,14 @@ class TelegramBot:
             greeting_text = f"Oh, hello {update.message.from_user.first_name}! Let me get to work!"
             await update.message.reply_text(greeting_text)
         else:
-            await update.message.reply_text("Sorry, I can't do that for you.")
+            await update.message.reply_text(_MSG_ADMIN_ONLY)
 
     async def tele_stop_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
         """
         Stop the bot and pause handling new messages (admin-only).
 
-        Only usernames in self.telegram['owners'] can execute this command.
+        Only usernames in self.telegram['owners'] can execute this command; otherwise, deny access.
         If the sender is an owner, sets self._online to False and confirms via reply.
-        Otherwise, denies access with "Sorry, I can't do that for you."
 
         Args:
             update: Telegram Update object containing the /stop message.
@@ -157,18 +169,41 @@ class TelegramBot:
             self._online = False
             await update.message.reply_text("Sure thing boss, cutting out!")
         else:
-            await update.message.reply_text("Sorry, I can't do that for you.")
+            await update.message.reply_text(_MSG_ADMIN_ONLY)
 
-    async def tele_wipe_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
+    async def tele_tools_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
         """
-        Permanently delete all conversation data from the database (admin-only).
+        List all registered tools available to this bot instance (admin-only, private chat only).
 
-        Only usernames in self.telegram['owners'] can execute this command.
-        If the sender is an owner, deletes all messages, users, and chats via wipe_all_data(),
-        clears in-memory conversations and token warnings, and confirms via reply.
-        Otherwise, denies access with "Sorry, I can't do that for you."
+        Shows name and description for every tool the bot exposes, including the built-in
+        search_messages tool and any webhook tools defined in config.yaml. Restricted to
+        bot_owner in a private chat; any other caller receives a generic denial.
+
+        Args:
+            update: Telegram Update object containing the /tools message.
+            context: Telegram context for sending the reply.
+        """
+        uname = update.message.from_user.username
+        chat_type = update.message.chat.type
+        if uname not in self.telegram['owners'] or chat_type != 'private':
+            await update.message.reply_text(_MSG_ADMIN_ONLY)
+            return
+        def _first_sentence(text: str) -> str:
+            return text.split('. ')[0].rstrip('.!?') + '.'
+
+        lines = ["Registered tools:"]
+        lines.append(f"- search_messages - {_first_sentence(_SEARCH_TOOL['description'])}")
+        for schema in self.webhook_schemas:
+            lines.append(f"- {schema['name']} - {_first_sentence(schema['description'])}")
+        await update.message.reply_text('\n'.join(lines))
+
+    async def tele_wipe_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
+        """
+        Prompt for inline keyboard confirmation before wiping all conversation data (admin-only).
 
-        This action is irreversible - all conversation history is permanently lost.
+        Only usernames in self.telegram['owners'] can execute this command, otherwise deny access.
+        Sends a confirmation message with Confirm and Cancel inline buttons, and the
+        actual wipe is handled by tele_wipe_callback() once the owner taps Confirm.
 
         Args:
             update: Telegram Update object containing the /wipe message.
@@ -176,12 +211,43 @@ class TelegramBot:
         """
         uname = update.message.from_user.username
         if uname not in self.telegram['owners']:
-            await update.message.reply_text("Sorry, I can't do that for you.")
+            await update.message.reply_text(_MSG_ADMIN_ONLY)
             return
-        await wipe_all_data()
-        self.conversations.clear()
-        self.token_warning.clear()
-        await update.message.reply_text("All conversation data wiped.")
+        keyboard = InlineKeyboardMarkup([[
+            InlineKeyboardButton("Confirm", callback_data=f"wipe:confirm:{uname}"),
+            InlineKeyboardButton("Cancel", callback_data=f"wipe:cancel:{uname}"),
+        ]])
+        await update.message.reply_text(_MSG_WIPE_PROMPT, reply_markup=keyboard)
+
+    async def tele_wipe_callback(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
+        """
+        Handle the inline keyboard confirmation for /wipe.
+
+        Executes the wipe if the tapping user matches the original /wipe sender and they tapped Confirm.
+        If they tapped Cancel, the wipe is suppressed and the confirmation message is edited
+        to show a cancellation notice. Ignores taps from any other user with an ephemeral alert.
+        Confirm calls wipe_all_data() and clears all in-memory conversation state.
+
+        Args:
+            update: Telegram Update containing the callback query.
+            context: Telegram context for answering the callback.
+        """
+        query = update.callback_query
+        parts = query.data.split(':')
+        action, original_uname = parts[1], parts[2]
+
+        if query.from_user.username != original_uname:
+            await query.answer(_MSG_NOT_YOUR_PROMPT)
+            return
+
+        await query.answer()
+        if action == 'confirm':
+            await wipe_all_data()
+            self.conversations.clear()
+            self.token_warning.clear()
+            await query.edit_message_text(_MSG_WIPE_COMPLETE)
+        else:
+            await query.edit_message_text(_MSG_WIPE_CANCELLED)
 
     async def tele_nick_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
         """
@@ -205,24 +271,57 @@ class TelegramBot:
 
     async def tele_forget_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
         """
-        Remove conversation history from the database (behavior depends on chat type).
+        Prompt for inline keyboard confirmation before removing the requester's conversation history.
 
-        In private chats: deletes all bot replies whose reply_to_id points to this user's messages,
-        then deletes the user's rows across all chats (full wipe including group messages),
-        then deletes any remaining messages in the private chat (pre-migration rows with NULL reply_to_id).
-        In group chats: deletes bot replies linked to this user's messages, then deletes the user's
-        rows across all chats, leaving other users' messages intact.
+        Executes the forget if the tapping user matches the original /forget sender
+        and they tapped Confirm. If they tapped Cancel, the forget is suppressed and
+        the confirmation message is edited to show a cancellation notice. Ignores taps
+        from any other user with an ephemeral alert.
 
-        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.
+        Args:
+            update: Telegram Update object containing the /forget message.
+            context: Telegram context for sending the reply.
         """
         validated = await self.tele_validate(update)
         if not validated:
             return
         (msg, chat, user) = validated
-        user_id = user.id
+        keyboard = InlineKeyboardMarkup([[
+            InlineKeyboardButton("Confirm", callback_data=f"forget:confirm:{user.id}"),
+            InlineKeyboardButton("Cancel", callback_data=f"forget:cancel:{user.id}"),
+        ]])
+        await msg.reply_text(_MSG_FORGET_PROMPT, reply_markup=keyboard)
+
+    async def tele_forget_callback(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
+        """
+        Handle the inline keyboard confirmation for /forget.
+
+        Executes the forget if the tapping user matches the original /forget sender and
+        they tapped Confirm. Cancels gracefully if they tapped Cancel. Ignores taps
+        from any other user with an ephemeral alert.
+        - In private chats: deletes bot replies linked to this user, all user rows across chats,
+          then remaining chat-level rows (pre-migration).
+        - In group chats: bot replies and user rows only, leaving other participants intact.
+
+        Args:
+            update: Telegram Update containing the callback query.
+            context: Telegram context for answering the callback.
+        """
+        query = update.callback_query
+        parts = query.data.split(':')
+        action, original_user_id = parts[1], int(parts[2])
+
+        if query.from_user.id != original_user_id:
+            await query.answer(_MSG_NOT_YOUR_PROMPT)
+            return
+
+        await query.answer()
+        if action == 'cancel':
+            await query.edit_message_text(_MSG_FORGET_CANCELLED)
+            return
+
+        chat = update.effective_chat
+        user_id = original_user_id
         chat_id = chat.id
         chat_type = chat.type
 
@@ -249,7 +348,7 @@ class TelegramBot:
             self.conversations.pop(evict_id, None)
             self.token_warning.pop(evict_id, None)
 
-        await msg.reply_text("My memories of our conversations are wiped!")
+        await query.edit_message_text(_MSG_FORGET_COMPLETE)
 
     async def tele_private_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
         """
@@ -394,16 +493,16 @@ class TelegramBot:
         url_match = re.search(r'\[http(s)?://\S+]', text)
 
         # Form the assistant's message based on low level easy stuff or send to the LLM
-        reply = "Sorry, I couldn't process your message! Please contact my creator."
+        reply = _MSG_PROCESS_ERROR
         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'])
         elif self._online and self.key_status.chat_enabled:
             # This is the transition point between quick Telegram replies and the LLM.
-            tools = [_SEARCH_TOOL]
+            tools = self._build_tool_list(chat_type, username)
             result = await self.llm_completion(chat_id, tools)
             if isinstance(result, ToolCall):
-                reply = await self._resolve_tool_call(result, conv, user_id)
+                reply = await self._resolve_tool_call(result, conv, user_id, username=username, chat_type=chat_type)
             else:
                 reply = result
 
@@ -577,7 +676,7 @@ class TelegramBot:
 
         # If it's a group text, only reply if the bot is named
         # The real magic of how the bot behaves is in tele_handle_response()
-        response = "Sorry, I couldn't process your message! Please contact my creator."
+        response = _MSG_PROCESS_ERROR
         assistant_db_id = None
         reply_context = ''
         if chat.type == 'supergroup' or chat.type == 'group':
@@ -671,26 +770,49 @@ class TelegramBot:
         if msg:
             await msg.reply_text("Sorry, I ran into an error! Please contact my creator.")
 
-    async def _handle_tool_call(self, tool_call: ToolCall, user_id: int, chat_id: int) -> str:
+    def _build_tool_list(self, chat_type: str, username: str | None) -> list:
         """
-        Execute a tool call requested by the LLM and return the result as a JSON string.
+        Build the tool list to pass to the LLM for this request.
 
-        Supports the 'search_messages' tool. Search results are scoped to chats accessible
-        to the requesting user: their private chat, the current chat (always included so the
-        current group is always searchable), and shared groups where the user and bot have
-        both sent messages.
+        Webhook tool schemas are only injected when two conditions are both true:
+        (1) the chat is a private chat, and (2) the requesting user is bot_owner.
+        In all other contexts only _SEARCH_TOOL is included so webhook tool names,
+        descriptions, and endpoint structure are never visible to group participants
+        or non-owner users.
 
         Args:
-            tool_call: The ToolCall returned by the provider.
-            user_id: Telegram user ID of the requesting user (for access control).
-            chat_id: Telegram chat ID of the current conversation (always included
-                     in accessible_chat_ids for search, ensuring current chat is searchable).
+            chat_type: Telegram chat type string ('private', 'group', 'supergroup', etc.).
+            username: Telegram username of the requesting user (without @), or None.
 
         Returns:
-            JSON-encoded list of result dicts with keys: speaker, chat, content, timestamp.
-            JSON-encoded ambiguity sentinel dict (with '_ambiguous': True) when speaker_query
-            or chat_query matched multiple entities; the LLM uses this to ask the user to clarify.
-            Returns a JSON error object on failure.
+            List of provider-compatible tool schema dicts.
+        """
+        tools = [_SEARCH_TOOL]
+        if chat_type == 'private' and username in self.telegram['owners']:
+            tools = tools + self.webhook_schemas
+        return tools
+
+    async def _handle_tool_call(
+        self, tool_call: ToolCall, user_id: int, chat_id: int,
+        username: str | None = None, chat_type: str = 'private',
+    ) -> str:
+        """
+        Execute a tool call requested by the LLM and return the result string.
+
+        Routes 'search_messages' to the built-in search handler. Webhook tools are
+        routed to execute_webhook() after a defense-in-depth permission check (primary
+        gate is _build_tool_list() which only injects webhook schemas for owner+private).
+
+        Args:
+            tool_call: The ToolCall returned by the provider.
+            user_id: Telegram user ID of the requesting user (for search access control).
+            chat_id: Telegram chat ID of the current conversation.
+            username: Telegram username of the requesting user (for webhook permission check).
+            chat_type: Telegram chat type string (for webhook permission check).
+
+        Returns either:
+            search_messages: JSON-encoded list of result dicts, JSON error object, or ambiguity sentinel.
+            webhook tools: framed '[Tool result from <name>]:' string, or error string.
         """
         if tool_call.name == 'search_messages':
             args = tool_call.arguments
@@ -715,9 +837,25 @@ class TelegramBot:
                         except ValueError:
                             pass
             return json.dumps(results)
+
+        tool_def = self.webhook_defs.get(tool_call.name)
+        if tool_def:
+            # Defense-in-depth guard: primary gate is _build_tool_list() not injecting schemas
+            # for non-owner or non-private contexts; this catches any edge case where a tool
+            # call arrives despite the schema not being injected.
+            if chat_type != 'private' or username not in self.telegram['owners']:
+                return "[Permission denied: webhook tools are only available in a private chat with the bot owner]"
+            return await execute_webhook(tool_def, tool_call.arguments)
+
         return json.dumps({"error": f"Unknown tool: {tool_call.name}"})
 
-    async def _resolve_tool_call(self, tool_call: ToolCall, conv: Conversation, user_id: int) -> str:
+    async def _resolve_tool_call(self,
+        tool_call: ToolCall,
+        conv: Conversation,
+        user_id: int,
+        username: str | None = None,
+        chat_type: str = 'private',
+    ) -> str:
         """
         Execute a tool call and perform the second LLM round-trip with results injected.
 
@@ -730,19 +868,21 @@ class TelegramBot:
             tool_call: The ToolCall returned by the first LLM call.
             conv: The active Conversation for this chat.
             user_id: Telegram user ID of the requesting user (for search access control).
+            username: Telegram username passed through to _handle_tool_call for webhook permission.
+            chat_type: Telegram chat type passed through to _handle_tool_call for webhook permission.
 
         Returns:
             The final LLM response string, or a fallback error message on failure.
         """
-        tool_result = await self._handle_tool_call(tool_call, user_id, conv.chat_id)
+        tool_result = await self._handle_tool_call(tool_call, user_id, conv.chat_id, username=username, chat_type=chat_type)
         ephemeral = list(conv.messages) + [
             {"role": "assistant", "content": "Let me handle that."},
-            {"role": "user", "content": f"Tool result:\n{tool_result}\n\nPlease respond to my request based on this result."},
+            {"role": "user", "content": f"Tool result:\n{tool_result}\n\nPlease respond to my original request based on this result. Be concise - do not repeat raw data from the tool result verbatim."},
         ]
         provider = get_provider(self.llm['chat_model'])
         try:
             result = await provider.complete(self.llm['chat_model'], ephemeral)
-            return result if isinstance(result, str) else "Sorry, I couldn't process the tool result."
+            return result if isinstance(result, str) else _MSG_TOOL_RESULT_ERROR
         except Exception as e:
             log_error(e, 'ToolCall')
             return "Sorry, I had trouble handling that request."
@@ -803,6 +943,8 @@ class TelegramBot:
         persona_prompt = INIT_BOT_CONFIG['persona_prompt'],
         key_status: ApiKeyStatus | None = None,
         log_name: str = 'tellmgrambot',
+        webhook_schemas: list | None = None,
+        webhook_defs: dict | None = None,
     ):
         """
         Initialize the Telegram bot with LLM configuration and API keys.
@@ -819,6 +961,10 @@ class TelegramBot:
             persona_temp: LLM temperature (0.0-2.0). If None, defaults to 1.0.
             persona_prompt: System prompt defining the bot's behavior and personality.
             key_status: ApiKeyStatus object indicating available features. If None, calls init_structure().
+            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).
+                          If None, no webhook tools are registered.
 
         Side Effects:
             - Normalises bot_owner to list[str] and stores in self.telegram['owners'].
@@ -836,6 +982,8 @@ 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
+        self.webhook_schemas = webhook_schemas or []  # Provider-compatible schemas for webhook tools
+        self.webhook_defs = webhook_defs or {}        # Resolved tool definitions keyed by name
         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
@@ -862,7 +1010,10 @@ class TelegramBot:
         self.telegram['app'].add_handler(CommandHandler('help', self.tele_commands))
         self.telegram['app'].add_handler(CommandHandler('start', self.tele_start_command))
         self.telegram['app'].add_handler(CommandHandler('stop', self.tele_stop_command))
+        self.telegram['app'].add_handler(CommandHandler('tools', self.tele_tools_command))
         self.telegram['app'].add_handler(CommandHandler('wipe', self.tele_wipe_command))
+        self.telegram['app'].add_handler(CallbackQueryHandler(self.tele_wipe_callback, pattern=r'^wipe:'))
+        self.telegram['app'].add_handler(CallbackQueryHandler(self.tele_forget_callback, pattern=r'^forget:'))
         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))
@@ -926,17 +1077,25 @@ class TelegramBot:
         # Bootstrap directories, logging, config, prompt (with appendix), and API keys in one call.
         key_status, config, prompt = init_structure(config_file, prompt_file, log_name)
 
+        # Build the webhook tool registry from the optional 'tools:' block in config.yaml.
+        webhook_schemas, webhook_defs = build_tool_registry(
+            config.get('tools', []),
+            allow_local=config.get('allow_local_webhooks', False),
+        )
+
         # Apply parameters to bot:
         return TelegramBot(
-            bot_owner      = config['bot_owner'],
-            bot_nickname   = config['bot_nickname'],
-            bot_initials   = config['bot_initials'],
-            chat_model     = config['chat_model'],
-            url_model      = config['url_model'],
-            token_limit    = config['token_limit'],
-            search_limit   = config['search_limit'],
-            persona_temp   = config['persona_temp'],
-            persona_prompt = prompt,
-            key_status     = key_status,
-            log_name       = log_name,
+            bot_owner       = config['bot_owner'],
+            bot_nickname    = config['bot_nickname'],
+            bot_initials    = config['bot_initials'],
+            chat_model      = config['chat_model'],
+            url_model       = config['url_model'],
+            token_limit     = config['token_limit'],
+            search_limit    = config['search_limit'],
+            persona_temp    = config['persona_temp'],
+            persona_prompt  = prompt,
+            key_status      = key_status,
+            log_name        = log_name,
+            webhook_schemas = webhook_schemas,
+            webhook_defs    = webhook_defs,
         )

tellmgrambot-3.11.0/TeLLMgramBot/tools.py

@@ -0,0 +1,273 @@
+"""
+Webhook tool registry and executor for TeLLMgramBot.
+
+Provides build_tool_registry() for startup parsing of config.yaml 'tools:' entries
+and execute_webhook() for dispatching HTTP tool calls at runtime.
+"""
+import ipaddress
+import logging
+import os
+import re
+import socket
+from urllib.parse import quote, urlparse
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+_RESPONSE_LOG_LIMIT = 200
+_RESPONSE_BODY_LIMIT = 4000
+_ENV_VAR_PATTERN = re.compile(r'\$([A-Z_][A-Z0-9_]*)')
+_PLACEHOLDER_PATTERN = re.compile(r'\{(\w+)\}')
+
+
+def _expand_env_vars(value: str) -> tuple:
+    """
+    Expand $UPPER_CASE_VAR references in a header value string.
+
+    Returns a two-tuple (expanded_value, first_missing_var_or_None). If any
+    referenced variable is not set, the first missing name is returned so the
+    caller can disable the tool rather than continue with an incomplete header.
+    """
+    missing = None
+
+    def _sub(m):
+        nonlocal missing
+        var = m.group(1)
+        val = os.environ.get(var)
+        if val is None and missing is None:
+            missing = var
+        return val or ''
+
+    return _ENV_VAR_PATTERN.sub(_sub, value), missing
+
+
+def _is_blocked_address(hostname: str) -> bool:
+    """
+    Return True if the hostname is, or resolves to, a loopback or link-local address.
+
+    Raw IP literals are checked without DNS. Hostnames are resolved via
+    socket.getaddrinfo; resolution failures are treated as not-blocked to avoid
+    incorrectly disabling tools when DNS is temporarily unavailable.
+
+    Only loopback (127.x.x.x, ::1) and link-local (169.254.x.x, fe80::/10) are
+    blocked. Private LAN addresses (192.168.x.x, 10.x.x.x, etc.) are permitted.
+    """
+    try:
+        addr = ipaddress.ip_address(hostname)
+        return addr.is_loopback or addr.is_link_local
+    except ValueError:
+        pass
+    try:
+        for _, _, _, _, sockaddr in socket.getaddrinfo(hostname, None):
+            try:
+                addr = ipaddress.ip_address(sockaddr[0])
+                if addr.is_loopback or addr.is_link_local:
+                    return True
+            except ValueError:
+                continue
+    except OSError:
+        pass
+    return False
+
+
+def build_tool_registry(
+    tools_config: list,
+    allow_local: bool = False,
+) -> tuple:
+    """
+    Parse raw tool config entries and build the webhook tool registry.
+
+    Validates all required fields ('name', 'description', 'webhook') and skips
+    entries missing any required field. Expands $ENV_VAR references in header
+    values at startup; tools whose header values reference missing environment
+    variables are excluded with a logged warning (graceful-degradation pattern).
+    Non-dict entries, non-dict headers values, and non-dict parameter definitions
+    are skipped with warnings. Duplicate tool names are deduplicated (first wins).
+
+    Args:
+        tools_config: List of raw tool definition dicts from config.yaml 'tools:' key.
+                      Pass an empty list or None to produce an empty registry.
+        allow_local: If True, the executor permits webhook URLs targeting loopback or
+                     link-local addresses. Mirrors the 'allow_local_webhooks' config key.
+
+    Returns:
+        Tuple of (schemas, defs) where:
+        - schemas: list of provider-compatible tool schema dicts (same shape as _SEARCH_TOOL).
+        - defs: dict mapping tool name -> resolved definition dict with expanded headers.
+    """
+    schemas = []
+    defs = {}
+
+    for entry in (tools_config or []):
+        if not isinstance(entry, dict):
+            logger.warning("Webhook tool entry is not a dict; skipping.")
+            continue
+        name = entry.get('name')
+        if not name:
+            logger.warning("Webhook tool entry missing 'name'; skipping.")
+            continue
+
+        # Expand $ENV_VAR references in header values; disable tool on first missing var
+        raw_headers = entry.get('headers') or {}
+        if not isinstance(raw_headers, dict):
+            logger.warning(f"Webhook tool '{name}': 'headers' must be a dict; treating as empty.")
+            raw_headers = {}
+        expanded_headers = {}
+        disabled = False
+        for header_name, header_value in raw_headers.items():
+            expanded, missing = _expand_env_vars(str(header_value))
+            if missing:
+                logger.warning(
+                    f"Webhook tool '{name}': header '{header_name}' references "
+                    f"missing env var ${missing}; tool disabled."
+                )
+                disabled = True
+                break
+            expanded_headers[header_name] = expanded
+        if disabled:
+            continue
+
+        # Validate required fields
+        webhook_url = entry.get('webhook', '')
+        if not webhook_url:
+            logger.warning(f"Webhook tool '{name}': missing 'webhook' URL; skipping.")
+            continue
+        description = entry.get('description', '')
+        if not description:
+            logger.warning(f"Webhook tool '{name}': missing 'description'; skipping.")
+            continue
+
+        # Duplicate name check - warn and skip to keep schemas/defs in sync
+        if name in defs:
+            logger.warning(f"Webhook tool '{name}': duplicate name; skipping.")
+            continue
+
+        # Build the provider-compatible schema from the parameters block
+        raw_params = entry.get('parameters') or {}
+        properties = {}
+        required = []
+        if isinstance(raw_params, dict):
+            for param_name, param_def in raw_params.items():
+                if not isinstance(param_def, dict):
+                    logger.warning(
+                        f"Webhook tool '{name}': parameter '{param_name}' definition "
+                        f"is not a dict; skipping parameter."
+                    )
+                    continue
+                prop = {'type': param_def.get('type', 'string')}
+                if 'description' in param_def:
+                    prop['description'] = param_def['description']
+                properties[param_name] = prop
+                if param_def.get('required', False):
+                    required.append(param_name)
+
+        schemas.append({
+            'name': name,
+            'description': description,
+            'parameters': {
+                'type': 'object',
+                'properties': properties,
+                'required': required,
+            },
+        })
+        defs[name] = {
+            'name': name,
+            'webhook': webhook_url,
+            'method': str(entry.get('method', 'POST')).upper(),
+            'headers': expanded_headers,
+            'normalize_args': entry.get('normalize_args'),
+            'allow_local': allow_local,
+        }
+
+    return schemas, defs
+
+
+async def execute_webhook(tool_def: dict, arguments: dict) -> str:
+    """
+    Execute a webhook tool call and return a framed result string for LLM injection.
+
+    Applies argument normalization, URL template substitution ({param} -> value),
+    and SSRF protection before firing the HTTP request. The response body is wrapped
+    with a '[Tool result from <name>]:' framing line so the LLM can distinguish
+    tool output from user instructions (prompt injection guard).
+
+    Request headers are never logged at any level. Response bodies are logged at
+    DEBUG only, truncated to 200 characters. Only tool name, HTTP method, base URL
+    (no query string), and status code are logged at INFO. The response body sent
+    to the LLM is truncated to 4000 characters to prevent overwhelming the context.
+
+    Args:
+        tool_def: Resolved tool definition dict from build_tool_registry defs.
+        arguments: Arguments dict from the LLM ToolCall.
+
+    Returns:
+        '[Tool result from <name>]:\n<body>' on success (2xx), or a descriptive
+        '[Tool error: ...]' string on failure (non-2xx, timeout, network error,
+        missing placeholder, SSRF block). Never raises.
+    """
+    name = tool_def['name']
+    url_template = tool_def['webhook']
+    method = tool_def['method']
+    headers = tool_def['headers']
+    normalize = tool_def.get('normalize_args')
+    allow_local = tool_def.get('allow_local', False)
+
+    args = dict(arguments)
+
+    # Normalize string arguments if requested (e.g. for case-sensitive resource IDs)
+    if normalize == 'lowercase':
+        args = {k: v.lower() if isinstance(v, str) else v for k, v in args.items()}
+
+    # Substitute {param} placeholders; remove them so they are not also sent in body/query
+    url = url_template
+    substituted = set()
+    for placeholder in _PLACEHOLDER_PATTERN.findall(url_template):
+        if placeholder not in args:
+            return f"[Tool error: required URL parameter '{placeholder}' was not provided]"
+        url = url.replace(f'{{{placeholder}}}', quote(str(args[placeholder]), safe=''))
+        substituted.add(placeholder)
+    for p in substituted:
+        args.pop(p, None)
+
+    # SSRF protection: block loopback and link-local unless explicitly allowed
+    parsed = urlparse(url)
+    if parsed.scheme not in ('http', 'https') or not parsed.hostname:
+        return f"[Tool error: '{name}' has an invalid or unsupported webhook URL]"
+    hostname = parsed.hostname
+    if not allow_local and _is_blocked_address(hostname):
+        logger.warning(f"Webhook '{name}': SSRF block - '{hostname}' is loopback or link-local")
+        return (
+            f"[Tool error: '{name}' targets a loopback or link-local address. "
+            f"Set allow_local_webhooks: true in config.yaml to permit local addresses.]"
+        )
+
+    host_part = f"{parsed.hostname}:{parsed.port}" if parsed.port else parsed.hostname
+    base_url = f"{parsed.scheme}://{host_part}{parsed.path}"
+    logger.info(f"Webhook '{name}': {method} {base_url}")
+
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            if method == 'GET':
+                resp = await client.get(url, params=args if args else None, headers=headers)
+            else:
+                resp = await client.request(method, url, json=args if args else None, headers=headers)
+
+        if not (200 <= resp.status_code < 300):
+            logger.warning(f"Webhook '{name}': status {resp.status_code}")
+            return f"[Tool error: '{name}' returned HTTP {resp.status_code}]"
+
+        logger.info(f"Webhook '{name}': status {resp.status_code}")
+        logger.debug(f"Webhook '{name}' response: {resp.text[:_RESPONSE_LOG_LIMIT]}")
+
+        body = resp.text
+        if len(body) > _RESPONSE_BODY_LIMIT:
+            body = body[:_RESPONSE_BODY_LIMIT] + f"\n[Response truncated at {_RESPONSE_BODY_LIMIT} characters]"
+        return f"[Tool result from {name}]:\n{body}"
+
+    except httpx.TimeoutException:
+        logger.warning(f"Webhook '{name}': request timed out")
+        return f"[Tool error: '{name}' timed out]"
+    except httpx.RequestError as e:
+        logger.warning(f"Webhook '{name}': {type(e).__name__}")
+        return f"[Tool error: '{name}' request failed ({type(e).__name__})]"

{tellmgrambot-3.10.4 → tellmgrambot-3.11.0}/TeLLMgramBot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.10.4
+Version: 3.11.0
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -122,9 +122,10 @@ os.environ['TELLMGRAMBOT_VIRUSTOTAL_API_KEY'] = my_vault.get('virustotal_key')
 
 ### Available Commands
 - `/nick <name>` - Set your nickname (for bot use in group chats).
-- `/forget` - Clear your conversation history. In private chats, clears everything and resets all active sessions. In group chats, removes only your messages.
+- `/forget` - Clear your conversation history. Shows a confirmation prompt before deletion. In private chats, clears everything and resets all active sessions. In group chats, removes only your messages.
 - `/private` - Toggle private mode (private chats only). When ON, your messages are excluded from group context loading.
-- `/help` - Display available commands and usage information. In private chats, if you are a bot owner, also shows administrator-only commands (`/start`, `/stop`, `/wipe`).
+- `/tools` - List all registered tools available to this bot instance (admin-only, private chat only). Shows the built-in search_messages tool and any webhook tools defined in config.yaml.
+- `/help` - Display available commands and usage information. In private chats, if you are a bot owner, also shows administrator-only commands (`/start`, `/stop`, `/wipe`, `/tools`).
 
 ### Group Chat Triggers
 The bot responds in groups when you:
@@ -151,6 +152,7 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `db_name`: Optional custom database filename without extension (e.g. `MyBot` creates `MyBot.db`); omit for default `conversations.db`. Use distinct names when running multiple bot instances in the same directory.
    - `token_limit`: Max tokens (optional; defaults to model's maximum)
    - `search_limit`: Max search results (optional; defaults to 30)
+   - `tools`: Optional list of webhook 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:**
    ```
    /setprivacy -> select your bot -> Disable

{tellmgrambot-3.10.4 → tellmgrambot-3.11.0}/TeLLMgramBot.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ TeLLMgramBot/database.py
 TeLLMgramBot/initialize.py
 TeLLMgramBot/message_handlers.py
 TeLLMgramBot/models.py
+TeLLMgramBot/tools.py
 TeLLMgramBot/utils.py
 TeLLMgramBot/web_utils.py
 TeLLMgramBot.egg-info/PKG-INFO

{tellmgrambot-3.10.4 → tellmgrambot-3.11.0}/setup.py

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