pythonclaw 0.2.0__py3-none-any.whl

pythonclaw/__init__.py

@@ -0,0 +1,17 @@
+"""PythonClaw — Open-source autonomous AI agent framework."""
+
+from . import config
+from .core.agent import Agent
+from .core.llm.base import LLMProvider
+from .core.llm.openai_compatible import OpenAICompatibleProvider
+from .init import init
+
+__version__ = "0.2.0"
+__all__ = [
+    "Agent",
+    "LLMProvider",
+    "OpenAICompatibleProvider",
+    "config",
+    "init",
+    "__version__",
+]

pythonclaw/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running PythonClaw as ``python -m pythonclaw``."""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

pythonclaw/channels/discord_bot.py

@@ -0,0 +1,231 @@
+"""
+Discord channel for PythonClaw.
+
+Session IDs: "discord:{user_id}" (DMs) or "discord:{channel_id}" (guilds)
+
+Commands
+--------
+  !reset          — discard and recreate the current session
+  !status         — show session info
+  !compact [hint] — compact conversation history
+  <text>          — forwarded to Agent.chat(), reply sent back
+
+The bot responds to:
+  - Direct messages (always)
+  - Channel mentions (@bot message) in guilds
+  - Optionally all messages in whitelisted channels
+
+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.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import discord
+
+from .. import config
+
+if TYPE_CHECKING:
+    from ..session_manager import SessionManager
+
+logger = logging.getLogger(__name__)
+
+MAX_MSG_LEN = 2000  # Discord message character limit
+
+
+class DiscordBot:
+    """
+    Discord channel — pure I/O layer.
+
+    Routes messages to the appropriate Agent via the shared SessionManager.
+    """
+
+    def __init__(
+        self,
+        session_manager: "SessionManager",
+        token: str,
+        allowed_users: list[int] | None = None,
+        allowed_channels: list[int] | None = None,
+    ) -> 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()
+
+        intents = discord.Intents.default()
+        intents.message_content = True
+        self._client = discord.Client(intents=intents)
+        self._setup_handlers()
+
+    # ── Session ID convention ─────────────────────────────────────────────────
+
+    @staticmethod
+    def _session_id(source_id: int, is_dm: bool = False) -> str:
+        prefix = "discord:dm" if is_dm else "discord"
+        return f"{prefix}:{source_id}"
+
+    # ── Access control ────────────────────────────────────────────────────────
+
+    def _is_allowed_user(self, user_id: int) -> bool:
+        if not self._allowed_users:
+            return True
+        return user_id in self._allowed_users
+
+    def _is_allowed_channel(self, channel_id: int) -> bool:
+        if not self._allowed_channels:
+            return True
+        return channel_id in self._allowed_channels
+
+    # ── Message splitting ─────────────────────────────────────────────────────
+
+    @staticmethod
+    def _split_message(text: str, limit: int = MAX_MSG_LEN) -> list[str]:
+        if len(text) <= limit:
+            return [text]
+        chunks = []
+        while text:
+            chunks.append(text[:limit])
+            text = text[limit:]
+        return chunks
+
+    # ── Handlers ──────────────────────────────────────────────────────────────
+
+    def _setup_handlers(self) -> None:
+        client = self._client
+
+        @client.event
+        async def on_ready():
+            logger.info("[Discord] Logged in as %s (id=%s)", client.user.name, client.user.id)
+
+        @client.event
+        async def on_message(message: discord.Message):
+            if message.author == client.user:
+                return
+            if message.author.bot:
+                return
+
+            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 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:
+                return
+
+            # Command dispatch
+            if content.startswith("!reset"):
+                await self._cmd_reset(message, is_dm)
+                return
+            if content.startswith("!status"):
+                await self._cmd_status(message, is_dm)
+                return
+            if content.startswith("!compact"):
+                hint = content[len("!compact"):].strip() or None
+                await self._cmd_compact(message, is_dm, hint)
+                return
+
+            await self._handle_chat(message, content, is_dm)
+
+    # ── Command implementations ───────────────────────────────────────────────
+
+    async def _cmd_reset(self, message: discord.Message, is_dm: bool) -> None:
+        sid = self._session_id(message.author.id if is_dm else message.channel.id, is_dm)
+        self._sm.reset(sid)
+        await message.reply("Session reset. Starting fresh!")
+
+    async def _cmd_status(self, message: discord.Message, 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)
+        from ..core.compaction import estimate_tokens
+        status = (
+            f"**Session Status**\n"
+            f"```\n"
+            f"Session ID   : {sid}\n"
+            f"Provider     : {type(agent.provider).__name__}\n"
+            f"Skills       : {len(agent.loaded_skill_names)} loaded\n"
+            f"Memories     : {len(agent.memory.list_all())} entries\n"
+            f"History      : {len(agent.messages)} messages\n"
+            f"Est. tokens  : ~{estimate_tokens(agent.messages)}\n"
+            f"Compactions  : {agent.compaction_count}\n"
+            f"```"
+        )
+        await message.reply(status)
+
+    async def _cmd_compact(self, message: discord.Message, is_dm: bool, hint: str | None) -> None:
+        sid = self._session_id(message.author.id if is_dm else message.channel.id, is_dm)
+        agent = self._sm.get_or_create(sid)
+        await message.reply("Compacting conversation history...")
+        try:
+            result = agent.compact(instruction=hint)
+        except Exception as exc:
+            logger.exception("[Discord] compact() raised an exception")
+            result = f"Compaction failed: {exc}"
+        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:
+        sid = self._session_id(message.author.id if is_dm else message.channel.id, is_dm)
+        agent = self._sm.get_or_create(sid)
+        async with message.channel.typing():
+            try:
+                response = agent.chat(content)
+            except Exception as exc:
+                logger.exception("[Discord] Agent.chat() raised an exception")
+                response = f"Sorry, something went wrong: {exc}"
+        for chunk in self._split_message(response or "(no response)"):
+            await message.reply(chunk)
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    async def start_async(self) -> None:
+        """Non-blocking start — for use inside an existing asyncio event loop."""
+        logger.info("[Discord] Starting bot (async mode)...")
+        await self._client.start(self._token)
+
+    async def stop_async(self) -> None:
+        logger.info("[Discord] Stopping bot...")
+        await self._client.close()
+
+
+# ── Utility ───────────────────────────────────────────────────────────────────
+
+def create_bot(session_manager: "SessionManager") -> "DiscordBot":
+    """Create a DiscordBot from pythonclaw.json / env vars."""
+    token = config.get_str(
+        "channels", "discord", "token", env="DISCORD_BOT_TOKEN",
+    )
+    if not token:
+        raise ValueError("Discord token not set (env DISCORD_BOT_TOKEN or channels.discord.token)")
+    allowed_users = config.get_int_list(
+        "channels", "discord", "allowedUsers", env="DISCORD_ALLOWED_USERS",
+    )
+    allowed_channels = config.get_int_list(
+        "channels", "discord", "allowedChannels", env="DISCORD_ALLOWED_CHANNELS",
+    )
+    return DiscordBot(
+        session_manager=session_manager,
+        token=token,
+        allowed_users=allowed_users or None,
+        allowed_channels=allowed_channels or None,
+    )
+
+
+# Backward-compatible alias
+create_bot_from_env = create_bot

pythonclaw/channels/telegram_bot.py

@@ -0,0 +1,236 @@
+"""
+Telegram channel for pythonclaw.
+
+Telegram is purely a *channel* — it handles sending and receiving messages.
+Session lifecycle (which Agent handles which chat) is delegated to the
+SessionManager, which is shared across all channels and the cron scheduler.
+
+Session IDs used by this channel: "telegram:{chat_id}"
+
+Commands
+--------
+  /start          — greeting + usage hint
+  /reset          — discard and recreate the current session
+  /status         — show session info (provider, skills, memory, tokens, compactions)
+  /compact [hint] — compact conversation history
+  <text>          — forwarded to Agent.chat(), reply sent back
+
+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.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from telegram import Update
+from telegram.ext import (
+    Application,
+    CommandHandler,
+    ContextTypes,
+    MessageHandler,
+    filters,
+)
+
+from .. import config
+
+if TYPE_CHECKING:
+    from ..session_manager import SessionManager
+
+logger = logging.getLogger(__name__)
+
+
+class TelegramBot:
+    """
+    Telegram channel — pure I/O layer.
+
+    Receives messages from Telegram and routes them to the appropriate Agent
+    via the shared SessionManager.  Does not own or manage Agent instances.
+    """
+
+    def __init__(
+        self,
+        session_manager: "SessionManager",
+        token: str,
+        allowed_users: list[int] | None = None,
+    ) -> None:
+        self._sm = session_manager
+        self._token = token
+        self._allowed_users: set[int] = set(allowed_users) if allowed_users else set()
+        self._app: Application | None = None
+
+    # ── Session ID convention ─────────────────────────────────────────────────
+
+    @staticmethod
+    def _session_id(chat_id: int) -> str:
+        return f"telegram:{chat_id}"
+
+    # ── Push message (called by cron / heartbeat) ─────────────────────────────
+
+    async def send_message(self, chat_id: int, text: str) -> None:
+        """Send a message to a specific chat (used by cron/heartbeat)."""
+        if self._app is None:
+            logger.warning("[Telegram] send_message called before bot is running")
+            return
+        await self._app.bot.send_message(chat_id=chat_id, text=text)
+
+    # ── Access control ────────────────────────────────────────────────────────
+
+    def _is_allowed(self, user_id: int) -> bool:
+        if not self._allowed_users:
+            return True
+        return user_id in self._allowed_users
+
+    async def _check_access(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> bool:
+        user = update.effective_user
+        if user is None or not self._is_allowed(user.id):
+            logger.warning("[Telegram] Rejected user_id=%s", user.id if user else "unknown")
+            await update.message.reply_text("Sorry, you are not authorised to use this bot.")
+            return False
+        return True
+
+    # ── Command handlers ──────────────────────────────────────────────────────
+
+    async def _cmd_start(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if not await self._check_access(update, context):
+            return
+        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"
+            "Commands:\n"
+            "  /start          — show this message\n"
+            "  /reset          — start a fresh session\n"
+            "  /status         — show session info\n"
+            "  /compact [hint] — compact conversation history"
+        )
+
+    async def _cmd_reset(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if not await self._check_access(update, context):
+            return
+        sid = self._session_id(update.effective_chat.id)
+        self._sm.reset(sid)
+        await update.message.reply_text("Session reset. Starting fresh! Send me a message.")
+
+    async def _cmd_status(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if not await self._check_access(update, context):
+            return
+        sid = self._session_id(update.effective_chat.id)
+        agent = self._sm.get_or_create(sid)
+        from ..core.compaction import estimate_tokens
+        await update.message.reply_text(
+            f"📊 Session Status\n"
+            f"  Session ID   : {sid}\n"
+            f"  Provider     : {type(agent.provider).__name__}\n"
+            f"  Skills       : {len(agent.loaded_skill_names)} loaded\n"
+            f"  Memories     : {len(agent.memory.list_all())} entries\n"
+            f"  History      : {len(agent.messages)} messages\n"
+            f"  Est. tokens  : ~{estimate_tokens(agent.messages):,}\n"
+            f"  Compactions  : {agent.compaction_count}\n"
+            f"  Total sessions: {len(self._sm)}"
+        )
+
+    async def _cmd_compact(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
+        if not await self._check_access(update, context):
+            return
+        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...")
+        try:
+            result = agent.compact(instruction=hint)
+        except Exception as exc:
+            result = f"Compaction failed: {exc}"
+        for chunk in _split_message(result):
+            await update.message.reply_text(chunk)
+
+    # ── Message handler ───────────────────────────────────────────────────────
+
+    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:
+            return
+        sid = self._session_id(update.effective_chat.id)
+        agent = self._sm.get_or_create(sid)
+        await update.message.chat.send_action("typing")
+        try:
+            response = agent.chat(user_text)
+        except Exception as exc:
+            logger.exception("[Telegram] Agent.chat() raised an exception")
+            response = f"Sorry, something went wrong: {exc}"
+        for chunk in _split_message(response or "(no response)"):
+            await update.message.reply_text(chunk)
+
+    # ── Lifecycle ─────────────────────────────────────────────────────────────
+
+    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))
+        self._app = app
+        return app
+
+    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.run_polling(drop_pending_updates=True)
+
+    async def start_async(self) -> None:
+        """Non-blocking start — for use inside an existing asyncio event loop."""
+        app = self.build_application()
+        logger.info("[Telegram] Initialising bot (async mode)...")
+        await app.initialize()
+        await app.start()
+        await app.updater.start_polling(drop_pending_updates=True)
+
+    async def stop_async(self) -> None:
+        if self._app is None:
+            return
+        logger.info("[Telegram] Stopping bot...")
+        await self._app.updater.stop()
+        await self._app.stop()
+        await self._app.shutdown()
+
+
+# ── Utility ───────────────────────────────────────────────────────────────────
+
+def _split_message(text: str, limit: int = 4096) -> list[str]:
+    """Split a long string into chunks that fit within Telegram's message limit."""
+    if len(text) <= limit:
+        return [text]
+    chunks = []
+    while text:
+        chunks.append(text[:limit])
+        text = text[limit:]
+    return chunks
+
+
+def create_bot(session_manager: "SessionManager") -> TelegramBot:
+    """Create a TelegramBot from pythonclaw.json / env vars."""
+    token = config.get_str(
+        "channels", "telegram", "token", env="TELEGRAM_BOT_TOKEN",
+    )
+    if not token:
+        raise ValueError("Telegram token not set (env TELEGRAM_BOT_TOKEN or channels.telegram.token)")
+    allowed_users = config.get_int_list(
+        "channels", "telegram", "allowedUsers", env="TELEGRAM_ALLOWED_USERS",
+    )
+    return TelegramBot(
+        session_manager=session_manager,
+        token=token,
+        allowed_users=allowed_users or None,
+    )
+
+
+# Backward-compatible alias
+create_bot_from_env = create_bot

pythonclaw/config.py

@@ -0,0 +1,190 @@
+"""
+Centralised configuration for PythonClaw.
+
+Load order (later sources override earlier ones):
+  1. pythonclaw.json in current working directory
+  2. ~/.pythonclaw/pythonclaw.json
+  3. Environment variables (highest priority)
+
+The JSON file supports // line comments and trailing commas for convenience
+(a subset of JSON5 that covers the most common needs).
+
+Usage
+-----
+    from pythonclaw import config
+
+    config.load()                       # call once at startup
+    provider = config.get("llm", "provider", env="LLM_PROVIDER", default="deepseek")
+    token    = config.get("channels", "telegram", "token", env="TELEGRAM_BOT_TOKEN")
+    users    = config.get_int_list("channels", "telegram", "allowedUsers",
+                                   env="TELEGRAM_ALLOWED_USERS")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+_TRAILING_COMMA_RE = re.compile(r",\s*([}\]])")
+
+_config: dict | None = None
+_config_path: Path | None = None
+
+
+def _strip_json5(text: str) -> str:
+    """Strip // comments and trailing commas so standard json.loads works.
+
+    Handles // inside quoted strings correctly (they are preserved).
+    """
+    result: list[str] = []
+    i = 0
+    n = len(text)
+    while i < n:
+        ch = text[i]
+        if ch == '"':
+            # Consume the entire string literal (including escaped chars)
+            j = i + 1
+            while j < n:
+                if text[j] == '\\':
+                    j += 2
+                elif text[j] == '"':
+                    j += 1
+                    break
+                else:
+                    j += 1
+            result.append(text[i:j])
+            i = j
+        elif ch == '/' and i + 1 < n and text[i + 1] == '/':
+            # Line comment — skip until end of line
+            while i < n and text[i] != '\n':
+                i += 1
+        else:
+            result.append(ch)
+            i += 1
+    text = "".join(result)
+    text = _TRAILING_COMMA_RE.sub(r"\1", text)
+    return text
+
+
+def _find_config_file() -> Path | None:
+    candidates = [
+        Path.cwd() / "pythonclaw.json",
+        Path.home() / ".pythonclaw" / "pythonclaw.json",
+    ]
+    for p in candidates:
+        if p.is_file():
+            return p
+    return None
+
+
+def _deep_get(data: dict, *keys: str, default: Any = None) -> Any:
+    current = data
+    for key in keys:
+        if not isinstance(current, dict):
+            return default
+        current = current.get(key)
+        if current is None:
+            return default
+    return current
+
+
+def load(path: str | Path | None = None, *, force: bool = False) -> dict:
+    """Load and cache configuration.  Safe to call multiple times.
+
+    Parameters
+    ----------
+    path   : explicit path to a JSON config file (overrides auto-discovery)
+    force  : if True, reload even if already cached
+    """
+    global _config, _config_path
+
+    if _config is not None and not force:
+        return _config
+
+    config_path = Path(path) if path else _find_config_file()
+    _config_path = config_path
+    raw: dict = {}
+
+    if config_path and config_path.is_file():
+        text = config_path.read_text(encoding="utf-8")
+        text = _strip_json5(text)
+        raw = json.loads(text)
+
+    _config = raw
+    return _config
+
+
+def get(*keys: str, env: str | None = None, default: Any = None) -> Any:
+    """Get a config value.  Env var takes priority over JSON.
+
+    Examples
+    --------
+    config.get("llm", "provider", env="LLM_PROVIDER", default="deepseek")
+    config.get("channels", "telegram", "token", env="TELEGRAM_BOT_TOKEN")
+    """
+    if _config is None:
+        load()
+
+    if env:
+        env_val = os.environ.get(env)
+        if env_val is not None:
+            return env_val
+
+    val = _deep_get(_config, *keys, default=default)
+    return val
+
+
+def get_int(*keys: str, env: str | None = None, default: int = 0) -> int:
+    """Get an integer config value."""
+    val = get(*keys, env=env, default=default)
+    return int(val) if val is not None else default
+
+
+def get_str(*keys: str, env: str | None = None, default: str = "") -> str:
+    """Get a string config value."""
+    val = get(*keys, env=env, default=default)
+    return str(val) if val is not None else default
+
+
+def get_list(*keys: str, env: str | None = None, default: list | None = None) -> list:
+    """Get a list value.  Env var is parsed as comma-separated."""
+    if _config is None:
+        load()
+
+    if env:
+        env_val = os.environ.get(env)
+        if env_val is not None and env_val.strip():
+            return [v.strip() for v in env_val.split(",") if v.strip()]
+
+    val = _deep_get(_config, *keys)
+    if isinstance(val, list):
+        return val
+    return default or []
+
+
+def get_int_list(*keys: str, env: str | None = None) -> list[int]:
+    """Get a list of integers.  Env var is parsed as comma-separated ints."""
+    raw = get_list(*keys, env=env)
+    return [int(v) for v in raw] if raw else []
+
+
+def config_path() -> Path | None:
+    """Return the path to the loaded config file, or None."""
+    return _config_path
+
+
+def as_dict() -> dict:
+    """Return a copy of the full loaded config dict."""
+    if _config is None:
+        load()
+    return dict(_config)
+
+
+def reset() -> None:
+    """Clear the cached config (mainly for testing)."""
+    global _config, _config_path
+    _config = None
+    _config_path = None