pythonclaw 0.2.0__py3-none-any.whl

pythonclaw/scheduler/heartbeat.py

@@ -0,0 +1,178 @@
+"""
+Heartbeat monitor for pythonclaw.
+
+Periodically sends a minimal probe to the configured LLM provider to verify
+that it is reachable and responding.  Results are:
+
+  * Logged to context/logs/heartbeat.log (rotating, max 1 MB x 3 files)
+  * Printed to stdout at DEBUG level
+  * Optionally sent as a Telegram alert when the provider becomes unreachable
+    (one alert per outage, not once per failed ping)
+
+Configuration (pythonclaw.json or env vars)
+-------------------------------------------
+  heartbeat.intervalSec  / HEARTBEAT_INTERVAL_SEC   — seconds between probes (default: 60)
+  heartbeat.alertChatId  / HEARTBEAT_ALERT_CHAT_ID  — Telegram chat_id to receive failure alerts
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import logging.handlers
+import os
+import time
+from typing import TYPE_CHECKING
+
+from .. import config
+
+if TYPE_CHECKING:
+    from ..channels.telegram_bot import TelegramBot
+    from ..core.llm.base import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_INTERVAL = 60
+LOG_DIR = os.path.join("context", "logs")
+LOG_FILE = os.path.join(LOG_DIR, "heartbeat.log")
+
+# Minimal probe message sent to the LLM
+_PROBE_MESSAGES = [{"role": "user", "content": "ping"}]
+
+
+class HeartbeatMonitor:
+    """Async heartbeat that pings the LLM provider on a fixed interval."""
+
+    def __init__(
+        self,
+        provider: "LLMProvider",
+        interval_sec: int = DEFAULT_INTERVAL,
+        telegram_bot: "TelegramBot | None" = None,
+        alert_chat_id: int | None = None,
+        log_path: str = LOG_FILE,
+    ) -> None:
+        self._provider = provider
+        self._interval = interval_sec
+        self._telegram_bot = telegram_bot
+        self._alert_chat_id = alert_chat_id
+        self._log_path = log_path
+        self._running = False
+        self._task: asyncio.Task | None = None
+        self._last_ok: bool | None = None  # track state to avoid alert storms
+        self._file_logger = _build_file_logger(log_path)
+
+    # ── Public API ───────────────────────────────────────────────────────────
+
+    async def start(self) -> None:
+        """Start the heartbeat loop as a background asyncio task."""
+        self._running = True
+        self._task = asyncio.create_task(self._loop(), name="heartbeat")
+        logger.info("[Heartbeat] Monitor started (interval=%ds)", self._interval)
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task and not self._task.done():
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        logger.info("[Heartbeat] Monitor stopped.")
+
+    # ── Internal loop ────────────────────────────────────────────────────────
+
+    async def _loop(self) -> None:
+        while self._running:
+            await self._probe()
+            await asyncio.sleep(self._interval)
+
+    async def _probe(self) -> None:
+        start = time.monotonic()
+        ok = False
+        error_msg = ""
+        try:
+            # Run the blocking provider call in a thread-pool so we don't block the event loop
+            response = await asyncio.get_event_loop().run_in_executor(
+                None,
+                lambda: self._provider.chat(messages=_PROBE_MESSAGES, tools=[], tool_choice="none"),
+            )
+            _ = response.choices[0].message.content  # verify structure
+            ok = True
+        except Exception as exc:
+            error_msg = str(exc)
+
+        latency_ms = int((time.monotonic() - start) * 1000)
+        self._log(ok, latency_ms, error_msg)
+        await self._maybe_alert(ok, error_msg)
+
+    def _log(self, ok: bool, latency_ms: int, error_msg: str) -> None:
+        status = "OK" if ok else "FAIL"
+        entry = f"[Heartbeat] {status} | latency={latency_ms}ms"
+        if not ok:
+            entry += f" | error={error_msg}"
+        if ok:
+            logger.debug(entry)
+        else:
+            logger.warning(entry)
+        self._file_logger.info(entry)
+
+    async def _maybe_alert(self, ok: bool, error_msg: str) -> None:
+        if self._telegram_bot is None or self._alert_chat_id is None:
+            self._last_ok = ok
+            return
+
+        if not ok and self._last_ok is not False:
+            # Transition to failure → send alert
+            msg = f"🚨 *Heartbeat FAILED*\n\nThe LLM provider is not responding.\n\nError: `{error_msg}`"
+            try:
+                await self._telegram_bot.send_message(self._alert_chat_id, msg)
+            except Exception as exc:
+                logger.error("[Heartbeat] Failed to send Telegram alert: %s", exc)
+        elif ok and self._last_ok is False:
+            # Recovered → send recovery notice
+            msg = "✅ *Heartbeat RECOVERED*\n\nThe LLM provider is responding again."
+            try:
+                await self._telegram_bot.send_message(self._alert_chat_id, msg)
+            except Exception as exc:
+                logger.error("[Heartbeat] Failed to send Telegram recovery: %s", exc)
+
+        self._last_ok = ok
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def _build_file_logger(log_path: str) -> logging.Logger:
+    os.makedirs(os.path.dirname(log_path), exist_ok=True)
+    file_logger = logging.getLogger("pythonclaw.heartbeat.file")
+    file_logger.setLevel(logging.INFO)
+    if not file_logger.handlers:
+        handler = logging.handlers.RotatingFileHandler(
+            log_path, maxBytes=1_000_000, backupCount=3, encoding="utf-8"
+        )
+        handler.setFormatter(logging.Formatter("%(asctime)s %(message)s"))
+        file_logger.addHandler(handler)
+    return file_logger
+
+
+def create_heartbeat(
+    provider: "LLMProvider",
+    telegram_bot: "TelegramBot | None" = None,
+) -> HeartbeatMonitor:
+    """Create a HeartbeatMonitor from pythonclaw.json / env vars."""
+    interval = config.get_int(
+        "heartbeat", "intervalSec", env="HEARTBEAT_INTERVAL_SEC", default=DEFAULT_INTERVAL,
+    )
+    raw_chat_id = config.get_str(
+        "heartbeat", "alertChatId", env="HEARTBEAT_ALERT_CHAT_ID",
+    )
+    alert_chat_id = int(raw_chat_id) if raw_chat_id else None
+    return HeartbeatMonitor(
+        provider=provider,
+        interval_sec=interval,
+        telegram_bot=telegram_bot,
+        alert_chat_id=alert_chat_id,
+    )
+
+
+# Backward-compatible alias
+create_heartbeat_from_env = create_heartbeat

pythonclaw/server.py

@@ -0,0 +1,145 @@
+"""
+Daemon server for PythonClaw — multi-channel mode.
+
+Supports Telegram and Discord channels, individually or combined.
+
+Architecture
+------------
+                    +----------------------------------------+
+                    |          SessionManager                 |
+                    |  "{channel}:{id}" → Agent               |
+                    |  "cron:{job_id}"  → Agent               |
+                    |  (Markdown-backed via SessionStore)      |
+                    +----------------------------------------+
+                               |
+          +--------------------+--------------------+
+          |                    |                    |
+    TelegramBot          CronScheduler       HeartbeatMonitor
+    DiscordBot           static + dynamic
+                         jobs
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+
+from .core.llm.base import LLMProvider
+from .core.persistent_agent import PersistentAgent
+from .core.session_store import SessionStore
+from .scheduler.cron import CronScheduler
+from .scheduler.heartbeat import create_heartbeat
+from .session_manager import SessionManager
+
+logger = logging.getLogger(__name__)
+
+
+async def run_server(
+    provider: LLMProvider,
+    channels: list[str] | None = None,
+) -> None:
+    """
+    Main entry point for daemon mode.
+
+    Parameters
+    ----------
+    provider  : the LLM provider to use
+    channels  : list of channels to start, e.g. ["telegram", "discord"].
+                Defaults to ["telegram"] for backward compatibility.
+    """
+    if channels is None:
+        channels = ["telegram"]
+
+    # ── 1. Session store (Markdown persistence) ───────────────────────────────
+    store = SessionStore()
+    logger.info("[Server] SessionStore initialised at '%s'", store.base_dir)
+
+    # ── 2. SessionManager (placeholder factory, updated below) ────────────────
+    session_manager = SessionManager(agent_factory=lambda sid: None, store=store)
+
+    # ── 3. CronScheduler ─────────────────────────────────────────────────────
+    jobs_path = os.path.join("context", "cron", "jobs.yaml")
+    scheduler = CronScheduler(
+        session_manager=session_manager,
+        jobs_path=jobs_path,
+    )
+
+    # ── 4. Real agent factory ─────────────────────────────────────────────────
+    def agent_factory(session_id: str) -> PersistentAgent:
+        return PersistentAgent(
+            provider=provider,
+            store=store,
+            session_id=session_id,
+            cron_manager=scheduler,
+            verbose=False,
+        )
+
+    session_manager.set_factory(agent_factory)
+
+    # ── 5. Start channels ─────────────────────────────────────────────────────
+    active_bots: list = []
+
+    if "telegram" in channels:
+        try:
+            from .channels.telegram_bot import create_bot_from_env
+            bot = create_bot_from_env(session_manager)
+            scheduler._telegram_bot = bot
+            await bot.start_async()
+            active_bots.append(bot)
+            logger.info("[Server] Telegram bot started.")
+        except (ValueError, ImportError) as exc:
+            logger.warning("[Server] Telegram skipped: %s", exc)
+
+    if "discord" in channels:
+        try:
+            from .channels.discord_bot import create_bot_from_env as create_discord
+            discord_bot = create_discord(session_manager)
+            asyncio.create_task(discord_bot.start_async())
+            active_bots.append(discord_bot)
+            logger.info("[Server] Discord bot started.")
+        except (ValueError, ImportError) as exc:
+            logger.warning("[Server] Discord skipped: %s", exc)
+
+    if not active_bots:
+        logger.error("[Server] No channels started. Check your pythonclaw.json configuration.")
+        return
+
+    # ── 6. Start scheduler ────────────────────────────────────────────────────
+    scheduler.start()
+
+    # ── 7. Heartbeat monitor ──────────────────────────────────────────────────
+    telegram_bot = next((b for b in active_bots if hasattr(b, '_app')), None)
+    heartbeat = create_heartbeat(provider=provider, telegram_bot=telegram_bot)
+    await heartbeat.start()
+
+    logger.info("[Server] All subsystems running (%s). Press Ctrl-C to stop.",
+                ", ".join(channels))
+
+    # ── Graceful shutdown ─────────────────────────────────────────────────────
+    stop_event = asyncio.Event()
+
+    def _signal_handler() -> None:
+        logger.info("[Server] Shutdown signal received.")
+        stop_event.set()
+
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, _signal_handler)
+        except (NotImplementedError, OSError):
+            pass
+
+    try:
+        await stop_event.wait()
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        pass
+    finally:
+        logger.info("[Server] Shutting down subsystems...")
+        await heartbeat.stop()
+        scheduler.stop()
+        for bot in active_bots:
+            if hasattr(bot, 'stop_async'):
+                await bot.stop_async()
+        logger.info("[Server] Shutdown complete.")

pythonclaw/session_manager.py

@@ -0,0 +1,104 @@
+"""
+SessionManager — central registry of session_id → Agent instances.
+
+All channels (Telegram, CLI, Web, etc.) and the cron scheduler go through a
+single SessionManager so that session lifecycle is managed in one place.
+
+Session ID conventions
+----------------------
+  telegram:{chat_id}   — one per Telegram chat
+  cron:{job_id}        — one per scheduled job (persistent across runs)
+  cli                  — the interactive REPL session
+  web:{connection_id}  — future web channel
+
+Factory signature
+-----------------
+The factory callable must accept the session_id as its first positional arg:
+
+    def factory(session_id: str) -> Agent: ...
+
+This lets PersistentAgent know which JSONL file to load/save.
+
+Usage
+-----
+    sm = SessionManager(agent_factory, store=session_store)
+    agent = sm.get_or_create("telegram:123456")
+    sm.reset("telegram:123456")   # deletes JSONL, creates fresh agent
+    sm.list_sessions()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .core.agent import Agent
+    from .core.session_store import SessionStore
+
+logger = logging.getLogger(__name__)
+
+# Factory receives the session_id so PersistentAgent can locate its JSONL file.
+AgentFactory = Callable[[str], "Agent"]
+
+
+class SessionManager:
+    """
+    Central registry that maps session_id strings to Agent instances.
+
+    Channels and schedulers call get_or_create(session_id) to obtain the
+    Agent for a given session.  This decouples session lifecycle from
+    channel-specific code.
+    """
+
+    def __init__(
+        self,
+        agent_factory: AgentFactory,
+        store: "SessionStore | None" = None,
+    ) -> None:
+        self._factory = agent_factory
+        self._store = store
+        self._sessions: dict[str, "Agent"] = {}
+
+    # ── Factory ──────────────────────────────────────────────────────────────
+
+    def set_factory(self, factory: AgentFactory) -> None:
+        """Late-bind the factory (used to resolve circular dependencies in server.py)."""
+        self._factory = factory
+
+    # ── Core API ─────────────────────────────────────────────────────────────
+
+    def get_or_create(self, session_id: str) -> "Agent":
+        """Return the existing Agent for session_id, creating one if needed."""
+        if session_id not in self._sessions:
+            logger.info("[SessionManager] Creating session '%s'", session_id)
+            self._sessions[session_id] = self._factory(session_id)
+        return self._sessions[session_id]
+
+    def reset(self, session_id: str) -> "Agent":
+        """Discard the current Agent, erase persisted history, and start fresh."""
+        logger.info("[SessionManager] Resetting session '%s'", session_id)
+        if self._store is not None:
+            self._store.delete(session_id)
+        self._sessions[session_id] = self._factory(session_id)
+        return self._sessions[session_id]
+
+    def remove(self, session_id: str) -> None:
+        """Remove a session from memory (JSONL file is kept unless store.delete is called)."""
+        if session_id in self._sessions:
+            del self._sessions[session_id]
+            logger.info("[SessionManager] Removed session '%s'", session_id)
+
+    def list_sessions(self) -> list[str]:
+        """Return all active (in-memory) session IDs."""
+        return list(self._sessions.keys())
+
+    def get(self, session_id: str) -> "Agent | None":
+        """Return the Agent for session_id, or None if it doesn't exist."""
+        return self._sessions.get(session_id)
+
+    def __len__(self) -> int:
+        return len(self._sessions)
+
+    def __contains__(self, session_id: str) -> bool:
+        return session_id in self._sessions

pythonclaw/templates/persona/demo_persona.md

@@ -0,0 +1,2 @@
+You are a SPACE EXPLORER agent. 🚀
+You speak with excitement about the cosmos and always use space emojis.

pythonclaw/templates/skills/communication/CATEGORY.md

@@ -0,0 +1,4 @@
+---
+name: communication
+description: Skills for sending emails, messages, and notifications.
+---

pythonclaw/templates/skills/communication/email/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: email
+description: >
+  Send emails via SMTP. Supports plain text and HTML, attachments, CC/BCC.
+  Use when the user asks to send any kind of email — notifications,
+  messages, reports, etc. Credentials are read from pythonclaw.json.
+---
+
+## Instructions
+
+Send emails through an SMTP server.  Credentials are stored in the
+`skills.email` section of `pythonclaw.json`.
+
+### Prerequisites
+
+The user must configure these fields in `pythonclaw.json` (or the web dashboard Config page):
+
+```json
+"skills": {
+  "email": {
+    "smtpServer": "smtp.gmail.com",
+    "smtpPort": 587,
+    "senderEmail": "you@gmail.com",
+    "senderPassword": "your-app-password"
+  }
+}
+```
+
+For Gmail, use an [App Password](https://myaccount.google.com/apppasswords).
+
+### Usage
+
+```bash
+python {skill_path}/send_email.py \
+  --to "recipient@example.com" \
+  --subject "Hello" \
+  --body "Message body here"
+```
+
+Optional flags:
+- `--cc "a@b.com,c@d.com"` — CC recipients
+- `--bcc "x@y.com"` — BCC recipients
+- `--html` — treat body as HTML
+
+### Examples
+
+- "Send an email to alice@example.com saying the report is ready"
+- "Email bob@company.com with subject 'Meeting Update' and body 'Rescheduled to 3pm'"
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `send_email.py` | Generic SMTP email sender |

pythonclaw/templates/skills/communication/email/send_email.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Generic SMTP email sender.  Reads credentials from pythonclaw.json."""
+
+import argparse
+import json
+import os
+import re
+import smtplib
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+
+def _load_email_config() -> dict:
+    """Load skills.email from pythonclaw.json."""
+    for path in ["pythonclaw.json", os.path.expanduser("~/.pythonclaw/pythonclaw.json")]:
+        if not os.path.isfile(path):
+            continue
+        with open(path, encoding="utf-8") as f:
+            text = f.read()
+        text = re.sub(r'//.*$', '', text, flags=re.MULTILINE)
+        text = re.sub(r',\s*([}\]])', r'\1', text)
+        data = json.loads(text)
+        return data.get("skills", {}).get("email", {})
+    return {}
+
+
+def send_email(
+    to: list[str],
+    subject: str,
+    body: str,
+    *,
+    cc: list[str] | None = None,
+    bcc: list[str] | None = None,
+    html: bool = False,
+) -> str:
+    cfg = _load_email_config()
+    server = cfg.get("smtpServer", "smtp.gmail.com")
+    port = int(cfg.get("smtpPort", 587))
+    sender = cfg.get("senderEmail", "")
+    password = cfg.get("senderPassword", "")
+
+    if not sender or not password:
+        return "Error: Email credentials not configured.  Set skills.email in pythonclaw.json."
+
+    msg = MIMEMultipart("alternative")
+    msg["From"] = sender
+    msg["To"] = ", ".join(to)
+    msg["Subject"] = subject
+    if cc:
+        msg["Cc"] = ", ".join(cc)
+
+    content_type = "html" if html else "plain"
+    msg.attach(MIMEText(body, content_type, "utf-8"))
+
+    all_recipients = list(to) + (cc or []) + (bcc or [])
+
+    try:
+        with smtplib.SMTP(server, port, timeout=30) as smtp:
+            smtp.ehlo()
+            smtp.starttls()
+            smtp.ehlo()
+            smtp.login(sender, password)
+            smtp.sendmail(sender, all_recipients, msg.as_string())
+        return f"Email sent to {', '.join(to)} (subject: {subject})"
+    except Exception as exc:
+        return f"Send failed: {exc}"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Send an email via SMTP.")
+    parser.add_argument("--to", required=True, help="Recipient(s), comma-separated")
+    parser.add_argument("--subject", required=True, help="Email subject line")
+    parser.add_argument("--body", required=True, help="Email body text")
+    parser.add_argument("--cc", default="", help="CC recipients, comma-separated")
+    parser.add_argument("--bcc", default="", help="BCC recipients, comma-separated")
+    parser.add_argument("--html", action="store_true", help="Treat body as HTML")
+    args = parser.parse_args()
+
+    to = [a.strip() for a in args.to.split(",") if a.strip()]
+    cc = [a.strip() for a in args.cc.split(",") if a.strip()] or None
+    bcc = [a.strip() for a in args.bcc.split(",") if a.strip()] or None
+
+    result = send_email(to, args.subject, args.body, cc=cc, bcc=bcc, html=args.html)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()

pythonclaw/templates/skills/data/CATEGORY.md

@@ -0,0 +1,4 @@
+---
+name: data
+description: Skills for fetching, scraping, and analysing external data sources.
+---

pythonclaw/templates/skills/data/csv_analyzer/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: csv_analyzer
+description: >
+  Analyze CSV and Excel files — statistics, filtering, grouping, and
+  data previews. Use when the user asks to read, analyze, query, or
+  summarize tabular data files (CSV, TSV, Excel).
+---
+
+## Instructions
+
+Analyze tabular data files using pandas.
+
+### Prerequisites
+
+Install dependency: `pip install pandas openpyxl`
+
+### Usage
+
+```bash
+python {skill_path}/analyze.py PATH [command] [options]
+```
+
+Commands:
+- `info` (default) — column types, shape, missing values
+- `head` — first N rows (default 10)
+- `stats` — descriptive statistics for numeric columns
+- `query` — filter rows with a pandas query expression
+- `groupby` — group-by aggregation
+- `columns` — list column names and types
+
+Options:
+- `--rows N` — number of rows for head (default 10)
+- `--query "col > 100"` — pandas query expression
+- `--groupby COL` — column to group by
+- `--agg mean|sum|count|min|max` — aggregation function (default: mean)
+- `--format json` — output as JSON
+- `--columns "col1,col2"` — select specific columns
+
+### Examples
+
+- "Show me what's in data.csv" → `analyze.py data.csv info`
+- "First 20 rows of sales.xlsx" → `analyze.py sales.xlsx head --rows 20`
+- "Statistics for revenue column" → `analyze.py data.csv stats --columns revenue`
+- "Filter rows where age > 30" → `analyze.py data.csv query --query "age > 30"`
+- "Average sales by region" → `analyze.py data.csv groupby --groupby region --columns sales --agg mean`
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `analyze.py` | Tabular data analyzer |