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

pythonclaw/__init__.py

@@ -6,7 +6,7 @@ from .core.llm.base import LLMProvider
 from .core.llm.openai_compatible import OpenAICompatibleProvider
 from .init import init
 
-__version__ = "0.3.3"
+__version__ = "0.5.0"
 __all__ = [
     "Agent",
     "LLMProvider",

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,24 @@ 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\u2026")
+
         async with message.channel.typing():
             try:
-                response = agent.chat(content)
+                async with self._sm.acquire(sid):
+                    import asyncio
+                    loop = asyncio.get_event_loop()
+                    response = await loop.run_in_executor(None, agent.chat, content)
             except Exception as exc:
                 logger.exception("[Discord] Agent.chat() raised an exception")
                 response = f"Sorry, something went wrong: {exc}"
@@ -219,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,19 +14,27 @@ 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
 
-from telegram import Update
+from telegram import BotCommand, ReactionTypeEmoji, Update
 from telegram.ext import (
     Application,
     CommandHandler,
@@ -56,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 ─────────────────────────────────────────────────
 
@@ -92,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:
@@ -100,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:
@@ -123,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"
@@ -140,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:
@@ -148,41 +183,131 @@ 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)
-        await update.message.chat.send_action("typing")
+
+        if self._sm.is_locked(sid):
+            await update.message.reply_text("\u23f3 Processing previous message\u2026")
+
         try:
-            response = agent.chat(user_text)
+            await update.message.set_reaction([ReactionTypeEmoji("\U0001f440")])
+        except Exception:
+            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?"
+            )
+
+        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, 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()
+
+        try:
+            await update.message.set_reaction([])
+        except Exception:
+            pass
+
         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:
+            while True:
+                await self._app.bot.send_chat_action(chat_id=chat_id, action="typing")
+                await asyncio.sleep(4)
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            logger.debug("[Telegram] _keep_typing stopped unexpectedly", exc_info=True)
+
     # ── Lifecycle ─────────────────────────────────────────────────────────────
 
+    _BOT_COMMANDS = [
+        BotCommand("start", "Show welcome message"),
+        BotCommand("reset", "Start a fresh session"),
+        BotCommand("status", "Show session info"),
+        BotCommand("compact", "Compact conversation history"),
+    ]
+
     def build_application(self) -> Application:
         app = Application.builder().token(self._token).build()
         app.add_handler(CommandHandler("start", self._cmd_start))
         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
 
+    async def _register_commands(self) -> None:
+        """Register slash-commands with Telegram so they appear in the menu."""
+        try:
+            await self._app.bot.set_my_commands(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)
+
     def run_polling(self) -> None:
         """Blocking call — starts the bot using long polling (for standalone use)."""
         app = self.build_application()
         logger.info("[Telegram] Starting bot (polling mode)...")
+        app.post_init = lambda _app: self._register_commands()
         app.run_polling(drop_pending_updates=True)
 
     async def start_async(self) -> None:
@@ -191,6 +316,7 @@ class TelegramBot:
         logger.info("[Telegram] Initialising bot (async mode)...")
         await app.initialize()
         await app.start()
+        await self._register_commands()
         await app.updater.start_polling(drop_pending_updates=True)
 
     async def stop_async(self) -> None:
@@ -225,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,
     )