pythonclaw 0.2.0__py3-none-any.whl

pythonclaw/onboard.py

@@ -0,0 +1,290 @@
+"""
+Interactive onboarding wizard for PythonClaw.
+
+Guides a new user through LLM provider selection, API key entry,
+and optional service key configuration.  Writes pythonclaw.json.
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+from pathlib import Path
+
+from . import config
+
+# ── ANSI helpers (no external deps) ──────────────────────────────────────────
+
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_GREEN = "\033[32m"
+_CYAN = "\033[36m"
+_YELLOW = "\033[33m"
+_RED = "\033[31m"
+_RESET = "\033[0m"
+
+
+def _c(text: str, color: str) -> str:
+    return f"{color}{text}{_RESET}"
+
+
+# ── Provider definitions ─────────────────────────────────────────────────────
+
+PROVIDERS = [
+    {
+        "key": "deepseek",
+        "name": "DeepSeek",
+        "default_model": "deepseek-chat",
+        "default_base": "https://api.deepseek.com/v1",
+        "env": "DEEPSEEK_API_KEY",
+    },
+    {
+        "key": "grok",
+        "name": "Grok (xAI)",
+        "default_model": "grok-3",
+        "default_base": "https://api.x.ai/v1",
+        "env": "GROK_API_KEY",
+    },
+    {
+        "key": "claude",
+        "name": "Claude (Anthropic)",
+        "default_model": "claude-sonnet-4-20250514",
+        "default_base": None,
+        "env": "ANTHROPIC_API_KEY",
+    },
+    {
+        "key": "gemini",
+        "name": "Gemini (Google)",
+        "default_model": "gemini-2.0-flash",
+        "default_base": None,
+        "env": "GEMINI_API_KEY",
+    },
+    {
+        "key": "kimi",
+        "name": "Kimi (Moonshot)",
+        "default_model": "moonshot-v1-128k",
+        "default_base": "https://api.moonshot.cn/v1",
+        "env": "KIMI_API_KEY",
+    },
+    {
+        "key": "glm",
+        "name": "GLM (Zhipu / ChatGLM)",
+        "default_model": "glm-4-flash",
+        "default_base": "https://open.bigmodel.cn/api/paas/v4/",
+        "env": "GLM_API_KEY",
+    },
+]
+
+
+# ── Core logic ───────────────────────────────────────────────────────────────
+
+def run_onboard(config_path: str | None = None) -> Path:
+    """Run the interactive onboarding wizard.  Returns path to saved config."""
+    print()
+    print(_c("  ╔══════════════════════════════════════╗", _CYAN))
+    print(_c("  ║       PythonClaw — Setup Wizard      ║", _CYAN))
+    print(_c("  ╚══════════════════════════════════════╝", _CYAN))
+    print()
+
+    # Load existing config if present
+    cfg = _load_existing(config_path)
+
+    # 1. Choose LLM provider
+    provider = _choose_provider(cfg)
+
+    # 2. Enter API key
+    api_key = _get_api_key(provider, cfg)
+
+    # 3. Update config
+    prov = provider["key"]
+    cfg.setdefault("llm", {})
+    cfg["llm"]["provider"] = prov
+    cfg["llm"].setdefault(prov, {})
+    cfg["llm"][prov]["apiKey"] = api_key
+    cfg["llm"][prov].setdefault("model", provider["default_model"])
+    if provider["default_base"]:
+        cfg["llm"][prov].setdefault("baseUrl", provider["default_base"])
+
+    # 4. Optional keys
+    _optional_keys(cfg)
+
+    # 5. Validate
+    _validate_key(cfg, provider)
+
+    # 6. Save
+    out_path = _save_config(cfg, config_path)
+
+    print()
+    print(_c("  ✔ Setup complete!", _GREEN))
+    print(f"    Config saved to: {_c(str(out_path), _BOLD)}")
+    print()
+    return out_path
+
+
+def _load_existing(config_path: str | None) -> dict:
+    """Load existing config or return empty dict."""
+    try:
+        config.load(config_path)
+        return config.as_dict()
+    except Exception:
+        return {}
+
+
+def _choose_provider(cfg: dict) -> dict:
+    current = cfg.get("llm", {}).get("provider", "")
+    print(_c("  Choose your LLM provider:", _BOLD))
+    print()
+    for i, p in enumerate(PROVIDERS, 1):
+        marker = _c(" (current)", _DIM) if p["key"] == current else ""
+        print(f"    {_c(str(i), _CYAN)}. {p['name']}{marker}")
+    print()
+
+    while True:
+        default_hint = ""
+        if current:
+            idx = next((i for i, p in enumerate(PROVIDERS) if p["key"] == current), None)
+            if idx is not None:
+                default_hint = f" [{idx + 1}]"
+
+        choice = input(f"  Enter number (1-{len(PROVIDERS)}){default_hint}: ").strip()
+        if not choice and current:
+            return next(p for p in PROVIDERS if p["key"] == current)
+        try:
+            n = int(choice)
+            if 1 <= n <= len(PROVIDERS):
+                selected = PROVIDERS[n - 1]
+                print(f"  → {_c(selected['name'], _GREEN)}")
+                print()
+                return selected
+        except ValueError:
+            pass
+        print(_c("  Invalid choice, try again.", _RED))
+
+
+def _get_api_key(provider: dict, cfg: dict) -> str:
+    existing = cfg.get("llm", {}).get(provider["key"], {}).get("apiKey", "")
+    has_existing = bool(existing) and existing != ""
+
+    hint = ""
+    if has_existing:
+        masked = existing[:4] + "****" + existing[-4:] if len(existing) > 8 else "****"
+        hint = f" (current: {masked}, press Enter to keep)"
+
+    print(f"  {provider['name']} API Key{hint}")
+    key = getpass.getpass("  API Key: ").strip()
+
+    if not key and has_existing:
+        print("  → Keeping existing key")
+        return existing
+    if not key:
+        print(_c("  API key is required.", _RED))
+        return _get_api_key(provider, cfg)
+
+    print(f"  → Key set ({key[:4]}****)")
+    print()
+    return key
+
+
+def _optional_keys(cfg: dict) -> None:
+    print(_c("  Optional services (press Enter to skip):", _DIM))
+    print()
+
+    # Tavily
+    tavily_existing = cfg.get("tavily", {}).get("apiKey", "")
+    if not tavily_existing:
+        tavily = input("  Tavily API Key (web search): ").strip()
+        if tavily:
+            cfg.setdefault("tavily", {})["apiKey"] = tavily
+            print("  → Tavily key set")
+
+    # Deepgram
+    dg_existing = cfg.get("deepgram", {}).get("apiKey", "")
+    if not dg_existing:
+        dg = input("  Deepgram API Key (voice input): ").strip()
+        if dg:
+            cfg.setdefault("deepgram", {})["apiKey"] = dg
+            print("  → Deepgram key set")
+
+    # SkillHub
+    sh_existing = cfg.get("skillhub", {}).get("apiKey", "")
+    if not sh_existing:
+        sh = input("  SkillHub API Key (marketplace): ").strip()
+        if sh:
+            cfg.setdefault("skillhub", {})["apiKey"] = sh
+            print("  → SkillHub key set")
+
+    print()
+
+
+def _validate_key(cfg: dict, provider: dict) -> None:
+    """Make a quick test call to validate the API key."""
+    print(f"  Validating {provider['name']} API key...", end=" ", flush=True)
+
+    prov_key = provider["key"]
+    api_key = cfg["llm"][prov_key]["apiKey"]
+
+    try:
+        if prov_key in ("deepseek", "grok", "kimi", "glm"):
+            from .core.llm.openai_compatible import OpenAICompatibleProvider
+            base_url = cfg["llm"][prov_key].get("baseUrl", provider["default_base"])
+            model = cfg["llm"][prov_key].get("model", provider["default_model"])
+            p = OpenAICompatibleProvider(api_key=api_key, base_url=base_url, model_name=model)
+            p.chat([{"role": "user", "content": "hi"}], max_tokens=5)
+        elif prov_key == "claude":
+            from .core.llm.anthropic_client import AnthropicProvider
+            p = AnthropicProvider(api_key=api_key)
+            p.chat([{"role": "user", "content": "hi"}], max_tokens=5)
+        elif prov_key == "gemini":
+            from .core.llm.gemini_client import GeminiProvider
+            p = GeminiProvider(api_key=api_key)
+            p.chat([{"role": "user", "content": "hi"}], max_tokens=5)
+        else:
+            print(_c("skipped (unknown provider type)", _YELLOW))
+            return
+
+        print(_c("✔ Valid!", _GREEN))
+    except Exception as exc:
+        err_str = str(exc)
+        if len(err_str) > 100:
+            err_str = err_str[:100] + "..."
+        print(_c(f"✘ {err_str}", _RED))
+        print(_c("  You can fix this later in pythonclaw.json or the web dashboard.", _DIM))
+
+
+def _save_config(cfg: dict, config_path: str | None) -> Path:
+    """Write config to disk."""
+    if config_path:
+        out = Path(config_path)
+    else:
+        out = Path.cwd() / "pythonclaw.json"
+
+    # Ensure default sections exist
+    cfg.setdefault("channels", {"telegram": {"token": "", "allowedUsers": []}, "discord": {"token": "", "allowedUsers": [], "allowedChannels": []}})
+    cfg.setdefault("tavily", {}).setdefault("apiKey", "")
+    cfg.setdefault("deepgram", {}).setdefault("apiKey", "")
+    cfg.setdefault("skillhub", {}).setdefault("apiKey", "")
+    cfg.setdefault("heartbeat", {"intervalSec": 60, "alertChatId": None})
+    cfg.setdefault("memory", {"dir": None})
+    cfg.setdefault("web", {"host": "0.0.0.0", "port": 7788})
+    cfg.setdefault("skills", {})
+    cfg.setdefault("agent", {"autoCompactThreshold": 0, "verbose": True})
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(cfg, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    config.load(str(out), force=True)
+    return out
+
+
+def needs_onboard(config_path: str | None = None) -> bool:
+    """Check if onboarding is needed (no config or no API key)."""
+    try:
+        config.load(config_path)
+    except Exception:
+        return True
+
+    provider = config.get_str("llm", "provider", default="")
+    if not provider:
+        return True
+
+    api_key = config.get_str("llm", provider, "apiKey", default="")
+    return not api_key

pythonclaw/scheduler/cron.py

@@ -0,0 +1,310 @@
+"""
+Cron-based LLM job scheduler for pythonclaw.
+
+Two sources of jobs
+-------------------
+1. Static jobs   — defined in context/cron/jobs.yaml (human-configured)
+2. Dynamic jobs  — added at runtime by the Agent via cron_add / cron_remove
+                   tool calls; persisted to context/cron/dynamic_jobs.json
+
+Session isolation
+-----------------
+Each job gets its own persistent session via the shared SessionManager:
+    session_id = "cron:{job_id}"
+
+This means:
+  - Jobs don't share context with each other or with user conversations.
+  - The same job accumulates history across multiple runs.
+  - Sessions can be reset via SessionManager.reset("cron:{job_id}").
+
+Agent cron tools
+----------------
+Expose these to the Agent via agent.py:
+    cron_add(job_id, cron, prompt, deliver_to_chat_id=None)
+    cron_remove(job_id)
+    cron_list()
+
+jobs.yaml format
+----------------
+jobs:
+  - id: daily_summary
+    cron: "0 9 * * *"
+    prompt: "Summarise my tasks and memory for today."
+    deliver_to: telegram
+    chat_id: 123456789
+    enabled: true
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import TYPE_CHECKING
+
+import yaml
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from apscheduler.triggers.cron import CronTrigger
+
+if TYPE_CHECKING:
+    from ..channels.telegram_bot import TelegramBot
+    from ..session_manager import SessionManager
+
+logger = logging.getLogger(__name__)
+
+DYNAMIC_JOBS_FILE = os.path.join("context", "cron", "dynamic_jobs.json")
+
+DEFAULT_JOBS_PATH = os.path.join("context", "cron", "jobs.yaml")
+
+
+class CronScheduler:
+    """
+    Loads job definitions from YAML and schedules them with APScheduler.
+
+    Each job runs inside its own session ("cron:{job_id}") managed by the
+    shared SessionManager, keeping job context isolated and persistent.
+    """
+
+    def __init__(
+        self,
+        session_manager: "SessionManager",
+        jobs_path: str = DEFAULT_JOBS_PATH,
+        telegram_bot: "TelegramBot | None" = None,
+    ) -> None:
+        self._sm = session_manager
+        self._jobs_path = jobs_path
+        self._telegram_bot = telegram_bot
+        self._scheduler = AsyncIOScheduler()
+
+    # ── YAML loading ─────────────────────────────────────────────────────────
+
+    def _load_jobs(self) -> list[dict]:
+        if not os.path.exists(self._jobs_path):
+            logger.info("[CronScheduler] No jobs file found at %s — skipping.", self._jobs_path)
+            return []
+        with open(self._jobs_path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+        return data.get("jobs", [])
+
+    # ── Job execution ────────────────────────────────────────────────────────
+
+    async def _run_job(
+        self,
+        job_id: str,
+        prompt: str,
+        deliver_to: str | None,
+        chat_id: int | None,
+    ) -> None:
+        session_id = f"cron:{job_id}"
+        logger.info("[CronScheduler] Running job '%s' (session='%s')", job_id, session_id)
+
+        agent = self._sm.get_or_create(session_id)
+        try:
+            response = agent.chat(prompt)
+            logger.info("[CronScheduler] Job '%s' completed.", job_id)
+        except Exception as exc:
+            logger.exception("[CronScheduler] Job '%s' failed: %s", job_id, exc)
+            response = f"[Cron job '{job_id}' failed]\n{exc}"
+
+        if deliver_to == "telegram" and chat_id and self._telegram_bot:
+            try:
+                header = f"📋 Cron job: {job_id}\n\n"
+                await self._telegram_bot.send_message(chat_id, header + (response or ""))
+            except Exception as exc:
+                logger.error(
+                    "[CronScheduler] Failed to deliver job '%s' to Telegram: %s", job_id, exc
+                )
+
+    # ── Scheduler lifecycle ──────────────────────────────────────────────────
+
+    def load_and_register_jobs(self) -> int:
+        """Parse jobs.yaml and register enabled jobs with APScheduler. Returns count."""
+        jobs = self._load_jobs()
+        registered = 0
+        for job in jobs:
+            job_id = job.get("id", "unnamed")
+            if not job.get("enabled", True):
+                logger.info("[CronScheduler] Skipping disabled job '%s'", job_id)
+                continue
+
+            cron_expr = job.get("cron")
+            prompt = job.get("prompt")
+            if not cron_expr or not prompt:
+                logger.warning(
+                    "[CronScheduler] Job '%s' is missing 'cron' or 'prompt' — skipped.", job_id
+                )
+                continue
+
+            deliver_to = job.get("deliver_to")
+            chat_id = job.get("chat_id")
+
+            trigger = _parse_cron(cron_expr)
+            self._scheduler.add_job(
+                self._run_job,
+                trigger=trigger,
+                id=job_id,
+                kwargs={
+                    "job_id": job_id,
+                    "prompt": prompt,
+                    "deliver_to": deliver_to,
+                    "chat_id": chat_id,
+                },
+                replace_existing=True,
+            )
+            logger.info(
+                "[CronScheduler] Registered job '%s' (session='cron:%s') cron='%s'",
+                job_id, job_id, cron_expr,
+            )
+            registered += 1
+
+        return registered
+
+    def start(self) -> None:
+        """Start the APScheduler background scheduler (static + dynamic jobs)."""
+        static_count = self.load_and_register_jobs()
+        dynamic_count = self._register_dynamic_jobs()
+        total = static_count + dynamic_count
+        if total == 0:
+            logger.info("[CronScheduler] No jobs to schedule — scheduler will start but be idle.")
+        self._scheduler.start()
+        logger.info(
+            "[CronScheduler] Scheduler started: %d static + %d dynamic job(s).",
+            static_count, dynamic_count,
+        )
+
+    def stop(self) -> None:
+        if self._scheduler.running:
+            self._scheduler.shutdown(wait=False)
+            logger.info("[CronScheduler] Scheduler stopped.")
+
+    def reload_jobs(self) -> int:
+        """Hot-reload static jobs from the YAML file without stopping the scheduler."""
+        self._scheduler.remove_all_jobs()
+        return self.load_and_register_jobs()
+
+    # ── Dynamic job management (called by Agent cron tools) ──────────────────
+
+    def _load_dynamic_jobs(self) -> dict[str, dict]:
+        """Load persisted dynamic jobs from JSON. Returns {job_id: job_dict}."""
+        if not os.path.exists(DYNAMIC_JOBS_FILE):
+            return {}
+        try:
+            with open(DYNAMIC_JOBS_FILE, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError) as exc:
+            logger.error("[CronScheduler] Failed to load dynamic jobs: %s", exc)
+            return {}
+
+    def _save_dynamic_jobs(self, jobs: dict[str, dict]) -> None:
+        os.makedirs(os.path.dirname(DYNAMIC_JOBS_FILE), exist_ok=True)
+        with open(DYNAMIC_JOBS_FILE, "w", encoding="utf-8") as f:
+            json.dump(jobs, f, indent=2, ensure_ascii=False)
+
+    def _register_dynamic_jobs(self) -> int:
+        """Register all persisted dynamic jobs with the scheduler."""
+        jobs = self._load_dynamic_jobs()
+        registered = 0
+        for job_id, job in jobs.items():
+            try:
+                self._scheduler.add_job(
+                    self._run_job,
+                    trigger=_parse_cron(job["cron"]),
+                    id=job_id,
+                    kwargs={
+                        "job_id": job_id,
+                        "prompt": job["prompt"],
+                        "deliver_to": job.get("deliver_to"),
+                        "chat_id": job.get("chat_id"),
+                    },
+                    replace_existing=True,
+                )
+                registered += 1
+                logger.info("[CronScheduler] Restored dynamic job '%s'", job_id)
+            except Exception as exc:
+                logger.error("[CronScheduler] Failed to restore dynamic job '%s': %s", job_id, exc)
+        return registered
+
+    def add_dynamic_job(
+        self,
+        job_id: str,
+        cron_expr: str,
+        prompt: str,
+        deliver_to: str | None = None,
+        chat_id: int | None = None,
+    ) -> str:
+        """
+        Add a new dynamic job (called from the Agent cron_add tool).
+        Persists to dynamic_jobs.json so it survives restarts.
+        """
+        try:
+            trigger = _parse_cron(cron_expr)
+        except ValueError as exc:
+            return f"Invalid cron expression: {exc}"
+
+        self._scheduler.add_job(
+            self._run_job,
+            trigger=trigger,
+            id=job_id,
+            kwargs={
+                "job_id": job_id,
+                "prompt": prompt,
+                "deliver_to": deliver_to,
+                "chat_id": chat_id,
+            },
+            replace_existing=True,
+        )
+
+        jobs = self._load_dynamic_jobs()
+        jobs[job_id] = {
+            "cron": cron_expr,
+            "prompt": prompt,
+            "deliver_to": deliver_to,
+            "chat_id": chat_id,
+        }
+        self._save_dynamic_jobs(jobs)
+        logger.info("[CronScheduler] Added dynamic job '%s' (cron='%s')", job_id, cron_expr)
+        return f"Job '{job_id}' scheduled: runs '{cron_expr}'. Session: cron:{job_id}."
+
+    def remove_dynamic_job(self, job_id: str) -> str:
+        """Remove a dynamic job (called from the Agent cron_remove tool)."""
+        jobs = self._load_dynamic_jobs()
+        if job_id not in jobs and not self._scheduler.get_job(job_id):
+            return f"Job '{job_id}' not found."
+        try:
+            self._scheduler.remove_job(job_id)
+        except Exception:
+            pass
+        jobs.pop(job_id, None)
+        self._save_dynamic_jobs(jobs)
+        logger.info("[CronScheduler] Removed dynamic job '%s'", job_id)
+        return f"Job '{job_id}' removed."
+
+    def list_jobs(self) -> str:
+        """Return a human-readable list of all active jobs (called from cron_list tool)."""
+        scheduler_jobs = self._scheduler.get_jobs()
+        dynamic = self._load_dynamic_jobs()
+        if not scheduler_jobs:
+            return "No scheduled jobs."
+        lines = []
+        for job in scheduler_jobs:
+            tag = "[dynamic]" if job.id in dynamic else "[static]"
+            next_run = job.next_run_time.strftime("%Y-%m-%d %H:%M %Z") if job.next_run_time else "paused"
+            lines.append(f"  {tag} {job.id} | next: {next_run}")
+        return "Active cron jobs:\n" + "\n".join(lines)
+
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+def _parse_cron(expr: str) -> CronTrigger:
+    """Convert a 5-field cron expression string into an APScheduler CronTrigger."""
+    parts = expr.strip().split()
+    if len(parts) != 5:
+        raise ValueError(f"Invalid cron expression (expected 5 fields): '{expr}'")
+    minute, hour, day, month, day_of_week = parts
+    return CronTrigger(
+        minute=minute,
+        hour=hour,
+        day=day,
+        month=month,
+        day_of_week=day_of_week,
+    )