pythonclaw 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

pythonclaw/channels/discord_bot.py

@@ -1,7 +1,7 @@
 """
 Discord channel for PythonClaw.
 
-Session IDs: "discord:{user_id}" (DMs) or "discord:{channel_id}" (guilds)
+Session IDs: "discord:dm:{user_id}" (DMs) or "discord:{channel_id}" (guilds)
 
 Commands
 --------
@@ -9,21 +9,29 @@ Commands
   !status         — show session info
   !compact [hint] — compact conversation history
   <text>          — forwarded to Agent.chat(), reply sent back
+  <image>         — image attachments sent to LLM for analysis
 
 The bot responds to:
   - Direct messages (always)
-  - Channel mentions (@bot message) in guilds
-  - Optionally all messages in whitelisted channels
+  - Channel mentions (@bot message) in guilds (when requireMention=true)
+  - All messages in whitelisted channels (when requireMention=false)
 
 Access control
 --------------
 Set DISCORD_ALLOWED_USERS to a comma-separated list of Discord user IDs.
 Set DISCORD_ALLOWED_CHANNELS to restrict which guild channels the bot listens in.
 Leave empty to allow all.
+
+Group behaviour
+---------------
+Set ``channels.discord.requireMention`` to ``true`` to require @bot mention
+in guild channels. Default is ``false`` (respond when mentioned OR in
+whitelisted channels).
 """
 
 from __future__ import annotations
 
+import base64
 import logging
 from typing import TYPE_CHECKING
 
@@ -52,11 +60,13 @@ class DiscordBot:
         token: str,
         allowed_users: list[int] | None = None,
         allowed_channels: list[int] | None = None,
+        require_mention: bool = False,
     ) -> None:
         self._sm = session_manager
         self._token = token
         self._allowed_users: set[int] = set(allowed_users) if allowed_users else set()
         self._allowed_channels: set[int] = set(allowed_channels) if allowed_channels else set()
+        self._require_mention = require_mention
 
         intents = discord.Intents.default()
         intents.message_content = True
@@ -113,20 +123,27 @@ class DiscordBot:
             is_dm = isinstance(message.channel, discord.DMChannel)
             is_mentioned = client.user in message.mentions if not is_dm else False
 
-            # In guilds, only respond to mentions or whitelisted channels
-            if not is_dm and not is_mentioned and not self._is_allowed_channel(message.channel.id):
-                return
+            if not is_dm:
+                if self._require_mention and not is_mentioned:
+                    return
+                if not self._require_mention and not is_mentioned:
+                    if not self._is_allowed_channel(message.channel.id):
+                        return
 
             if not self._is_allowed_user(message.author.id):
                 await message.reply("Sorry, you are not authorised to use this bot.")
                 return
 
             content = message.content.strip()
-            # Remove bot mention from the beginning
             if is_mentioned and client.user:
                 content = content.replace(f"<@{client.user.id}>", "").strip()
 
-            if not content:
+            has_image = any(
+                a.content_type and a.content_type.startswith("image/")
+                for a in message.attachments
+            )
+
+            if not content and not has_image:
                 return
 
             # Command dispatch
@@ -141,7 +158,35 @@ class DiscordBot:
                 await self._cmd_compact(message, is_dm, hint)
                 return
 
-            await self._handle_chat(message, content, is_dm)
+            chat_input = content or ""
+            if has_image:
+                chat_input = await self._build_image_input(
+                    message, content or "What's in this image?"
+                )
+
+            await self._handle_chat(message, chat_input, is_dm)
+
+    # ── Image handling ────────────────────────────────────────────────────────
+
+    @staticmethod
+    async def _build_image_input(message: discord.Message, caption: str) -> list:
+        """Download image attachments and build multimodal content array."""
+        parts: list[dict] = [{"type": "text", "text": caption}]
+        for att in message.attachments:
+            if att.content_type and att.content_type.startswith("image/"):
+                try:
+                    data = await att.read()
+                    b64 = base64.b64encode(data).decode()
+                    media_type = att.content_type.split(";")[0]
+                    parts.append({
+                        "type": "image_url",
+                        "image_url": {
+                            "url": f"data:{media_type};base64,{b64}",
+                        },
+                    })
+                except Exception:
+                    logger.warning("[Discord] Failed to download attachment %s", att.filename)
+        return parts
 
     # ── Command implementations ───────────────────────────────────────────────
 
@@ -180,12 +225,17 @@ class DiscordBot:
         for chunk in self._split_message(result or "(no result)"):
             await message.reply(chunk)
 
-    async def _handle_chat(self, message: discord.Message, content: str, is_dm: bool) -> None:
+    async def _handle_chat(
+        self,
+        message: discord.Message,
+        content: str | list,
+        is_dm: bool,
+    ) -> None:
         sid = self._session_id(message.author.id if is_dm else message.channel.id, is_dm)
         agent = self._sm.get_or_create(sid)
 
         if self._sm.is_locked(sid):
-            await message.reply("Processing previous message…")
+            await message.reply("Processing previous message\u2026")
 
         async with message.channel.typing():
             try:
@@ -226,11 +276,15 @@ def create_bot(session_manager: "SessionManager") -> "DiscordBot":
     allowed_channels = config.get_int_list(
         "channels", "discord", "allowedChannels", env="DISCORD_ALLOWED_CHANNELS",
     )
+    require_mention = config.get_bool(
+        "channels", "discord", "requireMention", default=False,
+    )
     return DiscordBot(
         session_manager=session_manager,
         token=token,
         allowed_users=allowed_users or None,
         allowed_channels=allowed_channels or None,
+        require_mention=require_mention,
     )
 
 

pythonclaw/channels/telegram_bot.py

@@ -14,16 +14,23 @@ Commands
   /status         — show session info (provider, skills, memory, tokens, compactions)
   /compact [hint] — compact conversation history
   <text>          — forwarded to Agent.chat(), reply sent back
+  <photo>         — image sent to LLM with optional caption
 
 Access control
 --------------
 Set TELEGRAM_ALLOWED_USERS to a comma-separated list of integer Telegram user
 IDs to restrict access.  Leave empty (or unset) to allow all users.
+
+Group behaviour
+---------------
+Set ``channels.telegram.requireMention`` to ``true`` in pythonclaw.json to
+require @bot mention in group chats.  DMs always respond.
 """
 
 from __future__ import annotations
 
 import asyncio
+import base64
 import logging
 from typing import TYPE_CHECKING
 
@@ -57,11 +64,14 @@ class TelegramBot:
         session_manager: "SessionManager",
         token: str,
         allowed_users: list[int] | None = None,
+        require_mention: bool = False,
     ) -> None:
         self._sm = session_manager
         self._token = token
         self._allowed_users: set[int] = set(allowed_users) if allowed_users else set()
+        self._require_mention = require_mention
         self._app: Application | None = None
+        self._bot_username: str | None = None
 
     # ── Session ID convention ─────────────────────────────────────────────────
 
@@ -93,6 +103,29 @@ class TelegramBot:
             return False
         return True
 
+    def _is_group(self, update: Update) -> bool:
+        """Return True if the message is from a group/supergroup."""
+        return update.effective_chat.type in ("group", "supergroup")
+
+    def _is_mentioned(self, update: Update) -> bool:
+        """Check if the bot is @mentioned in the message text."""
+        text = update.message.text or update.message.caption or ""
+        if self._bot_username and f"@{self._bot_username}" in text:
+            return True
+        entities = update.message.entities or update.message.caption_entities or []
+        for ent in entities:
+            if ent.type == "mention" and self._bot_username:
+                mention = text[ent.offset:ent.offset + ent.length]
+                if mention.lower() == f"@{self._bot_username.lower()}":
+                    return True
+        return False
+
+    def _strip_mention(self, text: str) -> str:
+        """Remove the @bot mention from message text."""
+        if self._bot_username:
+            text = text.replace(f"@{self._bot_username}", "").strip()
+        return text
+
     # ── Command handlers ──────────────────────────────────────────────────────
 
     async def _cmd_start(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
@@ -101,13 +134,14 @@ class TelegramBot:
         sid = self._session_id(update.effective_chat.id)
         self._sm.get_or_create(sid)
         await update.message.reply_text(
-            "👋 Hi! I'm your PythonClaw agent.\n\n"
-            "Just send me a message and I'll do my best to help.\n\n"
+            "\U0001f44b Hi! I'm your PythonClaw agent.\n\n"
+            "Just send me a message and I'll do my best to help.\n"
+            "You can also send photos and I'll analyze them.\n\n"
             "Commands:\n"
-            "  /start          — show this message\n"
-            "  /reset          — start a fresh session\n"
-            "  /status         — show session info\n"
-            "  /compact [hint] — compact conversation history"
+            "  /start          \u2014 show this message\n"
+            "  /reset          \u2014 start a fresh session\n"
+            "  /status         \u2014 show session info\n"
+            "  /compact [hint] \u2014 compact conversation history"
         )
 
     async def _cmd_reset(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
@@ -124,7 +158,7 @@ class TelegramBot:
         agent = self._sm.get_or_create(sid)
         from ..core.compaction import estimate_tokens
         await update.message.reply_text(
-            f"📊 Session Status\n"
+            f"\U0001f4ca Session Status\n"
             f"  Session ID   : {sid}\n"
             f"  Provider     : {type(agent.provider).__name__}\n"
             f"  Skills       : {len(agent.loaded_skill_names)} loaded\n"
@@ -141,7 +175,7 @@ class TelegramBot:
         sid = self._session_id(update.effective_chat.id)
         agent = self._sm.get_or_create(sid)
         hint: str | None = " ".join(context.args).strip() or None if context.args else None
-        await update.message.reply_text("⏳ Compacting conversation history...")
+        await update.message.reply_text("\u23f3 Compacting conversation history...")
         try:
             result = agent.compact(instruction=hint)
         except Exception as exc:
@@ -149,43 +183,55 @@ class TelegramBot:
         for chunk in _split_message(result):
             await update.message.reply_text(chunk)
 
-    # ── Message handler ───────────────────────────────────────────────────────
+    # ── Message handler (text + photos) ───────────────────────────────────────
 
     async def _handle_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         if not await self._check_access(update, context):
             return
-        user_text = (update.message.text or "").strip()
-        if not user_text:
+
+        if self._is_group(update) and self._require_mention:
+            if not self._is_mentioned(update):
+                return
+
+        user_text = (update.message.text or update.message.caption or "").strip()
+        user_text = self._strip_mention(user_text)
+
+        has_photo = bool(update.message.photo)
+
+        if not user_text and not has_photo:
             return
+
         sid = self._session_id(update.effective_chat.id)
         agent = self._sm.get_or_create(sid)
 
         if self._sm.is_locked(sid):
-            await update.message.reply_text("⏳ Processing previous message…")
+            await update.message.reply_text("\u23f3 Processing previous message\u2026")
 
-        # React to the message so the user knows the bot saw it
         try:
-            await update.message.set_reaction([ReactionTypeEmoji("👀")])
+            await update.message.set_reaction([ReactionTypeEmoji("\U0001f440")])
         except Exception:
-            pass  # reaction API may fail on older bot API or in groups
+            pass
+
+        # Build multimodal input if photo is present
+        chat_input = user_text or ""
+        if has_photo:
+            chat_input = await self._build_image_input(
+                update, user_text or "What's in this image?"
+            )
 
-        # Keep "typing…" visible for the entire duration of processing.
-        # Telegram's typing indicator expires after ~5 s, so we resend it
-        # on a loop until the agent finishes.
         typing_task = asyncio.create_task(
             self._keep_typing(update.message.chat_id)
         )
         try:
             async with self._sm.acquire(sid):
                 loop = asyncio.get_event_loop()
-                response = await loop.run_in_executor(None, agent.chat, user_text)
+                response = await loop.run_in_executor(None, agent.chat, chat_input)
         except Exception as exc:
             logger.exception("[Telegram] Agent.chat() raised an exception")
             response = f"Sorry, something went wrong: {exc}"
         finally:
             typing_task.cancel()
 
-        # Clear the "seen" reaction once we reply
         try:
             await update.message.set_reaction([])
         except Exception:
@@ -194,6 +240,23 @@ class TelegramBot:
         for chunk in _split_message(response or "(no response)"):
             await update.message.reply_text(chunk)
 
+    async def _build_image_input(self, update: Update, caption: str) -> list:
+        """Download photo and build a multimodal content array."""
+        photo = update.message.photo[-1]  # highest resolution
+        file = await photo.get_file()
+        data = await file.download_as_bytearray()
+        b64 = base64.b64encode(bytes(data)).decode()
+
+        return [
+            {"type": "text", "text": caption},
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:image/jpeg;base64,{b64}",
+                },
+            },
+        ]
+
     async def _keep_typing(self, chat_id: int) -> None:
         """Re-send the 'typing' chat action every 4 s until cancelled."""
         try:
@@ -220,7 +283,10 @@ class TelegramBot:
         app.add_handler(CommandHandler("reset", self._cmd_reset))
         app.add_handler(CommandHandler("status", self._cmd_status))
         app.add_handler(CommandHandler("compact", self._cmd_compact))
-        app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, self._handle_message))
+        app.add_handler(MessageHandler(
+            (filters.TEXT | filters.PHOTO) & ~filters.COMMAND,
+            self._handle_message,
+        ))
         self._app = app
         return app
 
@@ -228,7 +294,12 @@ class TelegramBot:
         """Register slash-commands with Telegram so they appear in the menu."""
         try:
             await self._app.bot.set_my_commands(self._BOT_COMMANDS)
-            logger.info("[Telegram] Registered %d bot commands", len(self._BOT_COMMANDS))
+            me = await self._app.bot.get_me()
+            self._bot_username = me.username
+            logger.info(
+                "[Telegram] Registered %d bot commands, username=@%s",
+                len(self._BOT_COMMANDS), self._bot_username,
+            )
         except Exception:
             logger.warning("[Telegram] Failed to register bot commands", exc_info=True)
 
@@ -280,10 +351,14 @@ def create_bot(session_manager: "SessionManager") -> TelegramBot:
     allowed_users = config.get_int_list(
         "channels", "telegram", "allowedUsers", env="TELEGRAM_ALLOWED_USERS",
     )
+    require_mention = config.get_bool(
+        "channels", "telegram", "requireMention", default=False,
+    )
     return TelegramBot(
         session_manager=session_manager,
         token=token,
         allowed_users=allowed_users or None,
+        require_mention=require_mention,
     )
 
 

pythonclaw/channels/whatsapp_bot.py

@@ -20,16 +20,23 @@ Commands
   !status         -- show session info
   !compact [hint] -- compact conversation history
   <text>          -- forwarded to Agent.chat(), reply sent back
+  <image>         -- image sent to LLM for analysis
 
 Access control
 --------------
 Set ``channels.whatsapp.allowedNumbers`` in ``pythonclaw.json`` to a list of
 E.164 phone numbers (without "+") to restrict access.  Leave empty to allow
 everyone.
+
+Group behaviour
+---------------
+Set ``channels.whatsapp.requireMention`` to ``true`` to require @bot mention
+in group chats.  DMs always respond.
 """
 
 from __future__ import annotations
 
+import base64
 import logging
 import threading
 from typing import TYPE_CHECKING
@@ -61,6 +68,7 @@ class WhatsAppBot:
         verify_token: str,
         callback_url: str | None = None,
         allowed_numbers: list[str] | None = None,
+        require_mention: bool = False,
     ) -> None:
         self._sm = session_manager
         self._phone_id = phone_id
@@ -68,8 +76,9 @@ class WhatsAppBot:
         self._verify_token = verify_token
         self._callback_url = callback_url
         self._allowed_numbers: set[str] = set(allowed_numbers) if allowed_numbers else set()
+        self._require_mention = require_mention
         self._wa = None  # set in mount()
-        self._locks: dict[str, threading.Lock] = {}  # per-session threading locks
+        self._locks: dict[str, threading.Lock] = {}
 
     # ── Session ID convention ─────────────────────────────────────────────────
 
@@ -92,10 +101,7 @@ class WhatsAppBot:
     # ── Mount on FastAPI ──────────────────────────────────────────────────────
 
     def mount(self, app: "FastAPI") -> None:
-        """Attach the PyWa webhook handler to *app*.
-
-        Must be called before the FastAPI server starts accepting requests.
-        """
+        """Attach the PyWa webhook handler to *app*."""
         try:
             from pywa import WhatsApp, types
         except ImportError:
@@ -116,7 +122,7 @@ class WhatsAppBot:
 
         wa = WhatsApp(**wa_kwargs)
         self._wa = wa
-        bot = self  # closure reference
+        bot = self
 
         @wa.on_message
         def _on_message(client: WhatsApp, msg: types.Message) -> None:
@@ -126,7 +132,20 @@ class WhatsAppBot:
                 return
 
             text = (msg.text or "").strip()
-            if not text:
+            has_image = msg.has_media and getattr(msg, "image", None) is not None
+
+            # Group mention check
+            is_group = getattr(msg, "is_group", False)
+            if is_group and bot._require_mention:
+                mentioned = False
+                if hasattr(msg, "mentioned") and msg.mentioned:
+                    mentioned = True
+                elif text and bot._phone_id:
+                    mentioned = bot._phone_id in text
+                if not mentioned:
+                    return
+
+            if not text and not has_image:
                 return
 
             sid = bot._session_id(wa_id)
@@ -161,13 +180,20 @@ class WhatsAppBot:
                     msg.reply(chunk)
                 return
 
+            # Build input (text or multimodal)
+            chat_input = text or "What's in this image?"
+            if has_image:
+                chat_input = _build_wa_image_input(
+                    client, msg, text or "What's in this image?"
+                )
+
             lock = bot._get_lock(sid)
             if lock.locked():
                 msg.reply("Processing previous message...")
 
             try:
                 with lock:
-                    response = agent.chat(text)
+                    response = agent.chat(chat_input)
             except Exception as exc:
                 logger.exception("[WhatsApp] Agent.chat() raised an exception")
                 response = f"Sorry, something went wrong: {exc}"
@@ -201,6 +227,27 @@ def _split_message(text: str, limit: int = 4096) -> list[str]:
     return chunks
 
 
+def _build_wa_image_input(client, msg, caption: str) -> list:
+    """Download WhatsApp image and build multimodal content array."""
+    try:
+        image = msg.image
+        data = image.download(in_memory=True)
+        b64 = base64.b64encode(data).decode()
+        media_type = getattr(image, "mime_type", "image/jpeg")
+        return [
+            {"type": "text", "text": caption},
+            {
+                "type": "image_url",
+                "image_url": {
+                    "url": f"data:{media_type};base64,{b64}",
+                },
+            },
+        ]
+    except Exception:
+        logger.warning("[WhatsApp] Failed to download image")
+        return caption
+
+
 def create_bot(session_manager: "SessionManager") -> WhatsAppBot:
     """Create a WhatsAppBot from pythonclaw.json / env vars."""
     phone_id = config.get_str(
@@ -239,6 +286,10 @@ def create_bot(session_manager: "SessionManager") -> WhatsAppBot:
         env="WHATSAPP_ALLOWED_NUMBERS",
     )
 
+    require_mention = config.get_bool(
+        "channels", "whatsapp", "requireMention", default=False,
+    )
+
     return WhatsAppBot(
         session_manager=session_manager,
         phone_id=phone_id,
@@ -246,6 +297,7 @@ def create_bot(session_manager: "SessionManager") -> WhatsAppBot:
         verify_token=verify_token,
         callback_url=callback_url,
         allowed_numbers=allowed_numbers or None,
+        require_mention=require_mention,
     )