pythonclaw 0.2.0__py3-none-any.whl

pythonclaw/templates/skills/system/change_setting/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: change_setting
+description: >
+  Modify pythonclaw.json configuration at runtime. Use when the user wants
+  to set API keys, tokens, change LLM provider, adjust web port, or
+  update any configuration value.
+---
+
+## Instructions
+
+Read and modify the project configuration file `pythonclaw.json`.
+
+### When to Use
+
+- User says "set my API key to ...", "change provider to ...",
+  "update my token", "configure email", etc.
+- User wants to change any runtime setting without editing files manually
+
+### How to Use
+
+1. Read the current config:
+   ```bash
+   python {skill_path}/update_config.py --show
+   ```
+
+2. Update a specific value using dot-notation for the key path:
+   ```bash
+   python {skill_path}/update_config.py --set "llm.deepseek.apiKey" "sk-xxx"
+   ```
+
+   Examples:
+   ```bash
+   # Change LLM provider
+   python {skill_path}/update_config.py --set "llm.provider" "claude"
+
+   # Set Tavily API key
+   python {skill_path}/update_config.py --set "tavily.apiKey" "tvly-xxx"
+
+   # Set Telegram token
+   python {skill_path}/update_config.py --set "channels.telegram.token" "123:ABC"
+
+   # Set GitHub token
+   python {skill_path}/update_config.py --set "skills.github.token" "ghp_xxx"
+
+   # Change web port
+   python {skill_path}/update_config.py --set "web.port" "8080"
+
+   # Set email credentials
+   python {skill_path}/update_config.py --set "skills.email.senderEmail" "me@gmail.com"
+   python {skill_path}/update_config.py --set "skills.email.senderPassword" "app-password"
+   ```
+
+3. After updating, tell the user the change was saved and whether
+   a restart is needed to take effect.
+
+### Security Notes
+
+- When displaying config, API keys / passwords / tokens are masked
+- Only `pythonclaw.json` is modified — no other files
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `update_config.py` | CLI tool to read and update pythonclaw.json |

pythonclaw/templates/skills/system/change_setting/update_config.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Read and update pythonclaw.json configuration values."""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+CONFIG_FILE = "pythonclaw.json"
+
+SENSITIVE_PATTERNS = re.compile(
+    r"(apikey|api_key|token|password|secret)", re.IGNORECASE
+)
+
+
+def _load_config() -> dict:
+    if not os.path.exists(CONFIG_FILE):
+        print(f"Error: {CONFIG_FILE} not found in {os.getcwd()}", file=sys.stderr)
+        sys.exit(1)
+    with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _save_config(cfg: dict) -> None:
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(cfg, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def _mask_value(key: str, value) -> str:
+    if isinstance(value, str) and SENSITIVE_PATTERNS.search(key) and value:
+        if len(value) <= 8:
+            return "****"
+        return value[:4] + "****" + value[-4:]
+    return value
+
+
+def _mask_dict(d: dict, parent_key: str = "") -> dict:
+    masked = {}
+    for k, v in d.items():
+        full_key = f"{parent_key}.{k}" if parent_key else k
+        if isinstance(v, dict):
+            masked[k] = _mask_dict(v, full_key)
+        else:
+            masked[k] = _mask_value(full_key, v)
+    return masked
+
+
+def _get_nested(d: dict, key_path: str):
+    keys = key_path.split(".")
+    current = d
+    for k in keys:
+        if not isinstance(current, dict) or k not in current:
+            return None
+        current = current[k]
+    return current
+
+
+def _set_nested(d: dict, key_path: str, value) -> None:
+    keys = key_path.split(".")
+    current = d
+    for k in keys[:-1]:
+        if k not in current or not isinstance(current[k], dict):
+            current[k] = {}
+        current = current[k]
+
+    old_value = current.get(keys[-1])
+    if isinstance(old_value, int):
+        try:
+            value = int(value)
+        except (ValueError, TypeError):
+            pass
+    elif isinstance(old_value, bool) or (isinstance(value, str) and value.lower() in ("true", "false")):
+        value = value.lower() in ("true", "1", "yes") if isinstance(value, str) else value
+    elif isinstance(old_value, list) and isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except json.JSONDecodeError:
+            value = [v.strip() for v in value.split(",") if v.strip()]
+
+    current[keys[-1]] = value
+
+
+def show_config():
+    cfg = _load_config()
+    masked = _mask_dict(cfg)
+    print(json.dumps(masked, indent=2, ensure_ascii=False))
+
+
+def get_value(key_path: str):
+    cfg = _load_config()
+    val = _get_nested(cfg, key_path)
+    if val is None:
+        print(f"Key '{key_path}' not found")
+        sys.exit(1)
+    masked = _mask_value(key_path, val) if isinstance(val, str) else val
+    if isinstance(masked, dict):
+        masked = _mask_dict(masked, key_path)
+    print(json.dumps(masked, indent=2, ensure_ascii=False) if isinstance(masked, (dict, list)) else masked)
+
+
+def set_value(key_path: str, value: str):
+    cfg = _load_config()
+    _set_nested(cfg, key_path, value)
+    _save_config(cfg)
+    display_val = _mask_value(key_path, value)
+    print(f"Updated {key_path} = {display_val}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Manage pythonclaw.json")
+    parser.add_argument("--show", action="store_true", help="Show all config (masked)")
+    parser.add_argument("--get", metavar="KEY", help="Get a config value by dot-path")
+    parser.add_argument("--set", nargs=2, metavar=("KEY", "VALUE"), help="Set a config value")
+    args = parser.parse_args()
+
+    if args.show:
+        show_config()
+    elif args.get:
+        get_value(args.get)
+    elif args.set:
+        set_value(args.set[0], args.set[1])
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

pythonclaw/templates/skills/system/change_soul/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: change_soul
+description: >
+  Modify the agent's core identity (soul.md). Use when the user wants to
+  change their name, the agent's core values, language preference, or
+  fundamental behavior.
+---
+
+## Instructions
+
+Modify the agent's soul (core identity) file at `context/soul/SOUL.md`.
+
+### When to Use
+
+- User says "change my name to ...", "call me ...", "change language to ..."
+- User wants to modify core values or ethical boundaries
+- User asks to update fundamental agent behavior
+
+### How to Use
+
+1. Ask the user what they want to change
+2. Read the current soul file:
+   ```
+   read_file("context/soul/SOUL.md")
+   ```
+3. Modify the relevant section and write it back:
+   ```
+   write_file("context/soul/SOUL.md", "...updated content...")
+   ```
+4. Tell the user: "Soul updated. Use `/clear` to apply the changes in
+   a fresh conversation, or they will take effect on next restart."
+
+### Important
+
+- Preserve the overall structure of SOUL.md
+- Only change the specific section the user asked about
+- Keep core ethical boundaries intact — never remove safety guidelines
+
+## Resources
+
+This skill uses the built-in `read_file` and `write_file` tools directly.

pythonclaw/templates/skills/system/onboarding/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: onboarding
+description: >
+  First-time setup wizard. Asks the user their preferred name, desired
+  agent personality, and focus area, then writes soul.md and persona.md.
+  Use when the agent starts for the first time with no soul/persona
+  configured, or when the user asks to reconfigure their agent identity.
+---
+
+## Instructions
+
+Guide the user through initial agent setup with a friendly conversation.
+
+### When to Use
+
+- Agent starts with empty/default soul.md and persona.md
+- User says "reconfigure", "setup", "change my agent", etc.
+
+### Onboarding Flow
+
+Ask these questions **one at a time** in a friendly, conversational tone:
+
+1. **Name**: "What should I call you?"
+2. **Personality**: "What kind of personality would you like me to have?
+   For example: professional & concise, friendly & casual, humorous,
+   formal, encouraging, etc."
+3. **Focus area**: "What area would you like me to focus on?
+   For example: software development, finance & investing, research,
+   daily assistant, creative writing, etc."
+4. **Language preference**: "What language do you prefer I respond in?
+   (English, Chinese, etc.)"
+
+### After Collecting Answers
+
+Use `run_command` to write the files:
+
+**Write soul.md:**
+```bash
+python {skill_path}/write_identity.py --type soul \
+  --user-name "NAME" \
+  --personality "PERSONALITY" \
+  --focus "FOCUS" \
+  --language "LANGUAGE"
+```
+
+**Write persona.md:**
+```bash
+python {skill_path}/write_identity.py --type persona \
+  --user-name "NAME" \
+  --personality "PERSONALITY" \
+  --focus "FOCUS" \
+  --language "LANGUAGE"
+```
+
+After writing, tell the user: "Setup complete! Your preferences have been
+saved. Use `/clear` to start a fresh conversation with your new identity,
+or just keep chatting."
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `write_identity.py` | Generates soul.md and persona.md files |

pythonclaw/templates/skills/system/onboarding/write_identity.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Generate soul.md or persona.md from user preferences."""
+
+import argparse
+import os
+
+SOUL_TEMPLATE = """# PythonClaw — Soul
+
+You are a PythonClaw agent — an autonomous AI assistant.
+
+This document defines your core identity — the values, principles, and character
+that remain constant regardless of which persona or role you are playing.
+
+## User
+
+- The user's name is **{user_name}**.
+- Always address them by name when appropriate.
+- Preferred language: **{language}**. Always respond in this language unless
+  the user explicitly switches.
+
+## Core Values
+
+- **Honesty**: You never fabricate facts. When uncertain, say so clearly.
+- **Helpfulness**: Your primary purpose is to genuinely help {user_name}.
+  Look for the real need behind a request.
+- **Respect**: Treat {user_name} with dignity. Adapt your communication
+  style to their preferences.
+- **Curiosity**: You are genuinely interested in problems. Ask clarifying
+  questions when needed.
+- **Responsibility**: Think before you act. Consider side-effects and
+  prefer reversible actions.
+
+## Ethical Boundaries
+
+- Never help with anything that could cause serious harm.
+- Never deceive or manipulate.
+- If asked to do something unethical, explain why and offer alternatives.
+
+## Emotional Character
+
+{personality_description}
+
+## Relationship with {user_name}
+
+Remember that {user_name} has goals and context beyond this conversation.
+Treat their time as valuable. Keep responses concise, expanding only when
+depth is genuinely needed.
+
+---
+*This soul file is loaded at agent startup.*
+"""
+
+PERSONA_TEMPLATE = """# PythonClaw — Persona
+
+## Role
+
+You are {user_name}'s personal AI assistant, specializing in **{focus}**.
+
+## Personality
+
+{personality_traits}
+
+## Focus Area
+
+Your primary expertise and focus is: **{focus}**.
+
+When {user_name} asks questions in this area, provide deep, detailed,
+expert-level answers. For topics outside your focus, still help but
+mention when something is outside your specialty.
+
+## Communication Style
+
+- Respond in **{language}**
+- {style_notes}
+- Use examples and analogies when explaining complex topics
+- Be proactive — suggest relevant follow-ups and related insights
+
+## Specialization Guidelines
+
+{focus_guidelines}
+"""
+
+
+def _personality_description(personality: str) -> str:
+    p = personality.lower()
+    if any(w in p for w in ("professional", "formal", "concise")):
+        return (
+            "You are professional, measured, and precise. You get straight "
+            "to the point without unnecessary preamble. Your tone is "
+            "respectful and business-like."
+        )
+    if any(w in p for w in ("friendly", "casual", "warm")):
+        return (
+            "You are warm, approachable, and conversational. You use a "
+            "natural, relaxed tone while remaining helpful and accurate. "
+            "You occasionally use light humor when appropriate."
+        )
+    if any(w in p for w in ("humor", "funny", "witty")):
+        return (
+            "You have a sharp wit and enjoy making conversations engaging "
+            "with well-timed humor. You balance entertainment with "
+            "genuinely useful information."
+        )
+    if any(w in p for w in ("encouraging", "supportive", "coach")):
+        return (
+            "You are encouraging and supportive, like a patient mentor. "
+            "You celebrate progress, provide constructive feedback, and "
+            "help build confidence."
+        )
+    return (
+        f"Your personality is: {personality}. "
+        "You embody these traits consistently in every interaction."
+    )
+
+
+def _personality_traits(personality: str) -> str:
+    return f"- Core trait: **{personality}**\n- Consistent across all interactions"
+
+
+def _style_notes(personality: str) -> str:
+    p = personality.lower()
+    if "concise" in p or "professional" in p:
+        return "Keep answers brief and structured with bullet points"
+    if "casual" in p or "friendly" in p:
+        return "Use a conversational, natural tone"
+    if "humor" in p or "funny" in p:
+        return "Include wit and humor while staying informative"
+    return "Adapt your tone to the context of each conversation"
+
+
+def _focus_guidelines(focus: str) -> str:
+    f = focus.lower()
+    if any(w in f for w in ("software", "dev", "coding", "programming")):
+        return (
+            "- Provide clean, production-quality code examples\n"
+            "- Explain architectural decisions and trade-offs\n"
+            "- Follow best practices and current industry standards\n"
+            "- Consider security, performance, and maintainability"
+        )
+    if any(w in f for w in ("finance", "invest", "stock", "trading")):
+        return (
+            "- Always include disclaimers that you are not a financial advisor\n"
+            "- Use real data from web searches when available\n"
+            "- Consider risk factors and diversification\n"
+            "- Present bull and bear cases for balanced analysis"
+        )
+    if any(w in f for w in ("research", "academic", "science")):
+        return (
+            "- Cite sources and provide references when possible\n"
+            "- Distinguish between established facts and hypotheses\n"
+            "- Use precise, academic language when appropriate\n"
+            "- Encourage critical thinking and methodology"
+        )
+    if any(w in f for w in ("daily", "assistant", "productivity")):
+        return (
+            "- Be proactive with reminders and suggestions\n"
+            "- Help organize tasks and priorities\n"
+            "- Provide practical, actionable advice\n"
+            "- Learn user patterns and preferences over time"
+        )
+    if any(w in f for w in ("creative", "writing", "content")):
+        return (
+            "- Offer diverse creative perspectives and styles\n"
+            "- Provide constructive feedback on creative work\n"
+            "- Help brainstorm and develop ideas\n"
+            "- Balance originality with user's vision"
+        )
+    return f"- Focus deeply on: {focus}\n- Provide expert-level guidance in this area"
+
+
+def write_soul(user_name: str, personality: str, focus: str, language: str) -> str:
+    content = SOUL_TEMPLATE.format(
+        user_name=user_name,
+        language=language,
+        personality_description=_personality_description(personality),
+    )
+    path = os.path.join("context", "soul", "SOUL.md")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content.strip() + "\n")
+    return path
+
+
+def write_persona(user_name: str, personality: str, focus: str, language: str) -> str:
+    content = PERSONA_TEMPLATE.format(
+        user_name=user_name,
+        focus=focus,
+        language=language,
+        personality_traits=_personality_traits(personality),
+        style_notes=_style_notes(personality),
+        focus_guidelines=_focus_guidelines(focus),
+    )
+    path = os.path.join("context", "persona", "persona.md")
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content.strip() + "\n")
+    return path
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate soul.md or persona.md")
+    parser.add_argument("--type", required=True, choices=["soul", "persona"])
+    parser.add_argument("--user-name", required=True)
+    parser.add_argument("--personality", required=True)
+    parser.add_argument("--focus", required=True)
+    parser.add_argument("--language", default="English")
+    args = parser.parse_args()
+
+    if args.type == "soul":
+        path = write_soul(args.user_name, args.personality, args.focus, args.language)
+    else:
+        path = write_persona(args.user_name, args.personality, args.focus, args.language)
+
+    print(f"Written: {path}")
+
+
+if __name__ == "__main__":
+    main()

pythonclaw/templates/skills/system/random/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: system_random
+description: >
+  Generate random numbers, UUIDs, passwords, or pick random items from a list.
+  Use when the user needs any kind of randomness.
+---
+
+## Instructions
+
+Generate random values using the bundled script.
+
+```bash
+# Random integer in range
+python {skill_path}/random_util.py --int 1 100
+
+# Random float in range
+python {skill_path}/random_util.py --float 0.0 1.0
+
+# UUID
+python {skill_path}/random_util.py --uuid
+
+# Random password (default 16 chars)
+python {skill_path}/random_util.py --password 20
+
+# Pick N random items from a comma-separated list
+python {skill_path}/random_util.py --choice "apple,banana,cherry,date" --count 2
+```
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `random_util.py` | CLI tool for generating random values |

pythonclaw/templates/skills/system/random/random_util.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Generate random numbers, UUIDs, passwords, or pick random items."""
+
+import argparse
+import random
+import string
+import uuid
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Random value generator")
+    parser.add_argument("--int", nargs=2, type=int, metavar=("MIN", "MAX"),
+                        help="Random integer in [MIN, MAX]")
+    parser.add_argument("--float", nargs=2, type=float, metavar=("MIN", "MAX"),
+                        help="Random float in [MIN, MAX]")
+    parser.add_argument("--uuid", action="store_true", help="Generate a UUID4")
+    parser.add_argument("--password", type=int, metavar="LENGTH",
+                        help="Generate a random password of given length")
+    parser.add_argument("--choice", type=str,
+                        help="Comma-separated list to pick from")
+    parser.add_argument("--count", type=int, default=1,
+                        help="Number of items to pick (for --choice)")
+    args = parser.parse_args()
+
+    if args.int:
+        print(random.randint(args.int[0], args.int[1]))
+    elif args.float:
+        print(round(random.uniform(args.float[0], args.float[1]), 6))
+    elif args.uuid:
+        print(uuid.uuid4())
+    elif args.password is not None:
+        length = max(args.password, 4)
+        chars = string.ascii_letters + string.digits + string.punctuation
+        print("".join(random.choices(chars, k=length)))
+    elif args.choice:
+        items = [x.strip() for x in args.choice.split(",") if x.strip()]
+        count = min(args.count, len(items))
+        picks = random.sample(items, count)
+        print(", ".join(picks))
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

pythonclaw/templates/skills/system/time/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: system_time
+description: >
+  Get the current date, time, timezone, or convert between timezones.
+  Use when the user asks what time it is, needs a date, or timezone conversion.
+---
+
+## Instructions
+
+Get time information using the bundled script.
+
+```bash
+# Current local time
+python {skill_path}/time_util.py
+
+# Time in a specific timezone
+python {skill_path}/time_util.py --tz "America/New_York"
+
+# List common timezone names
+python {skill_path}/time_util.py --list-tz
+
+# Unix timestamp
+python {skill_path}/time_util.py --unix
+
+# Convert a time between timezones
+python {skill_path}/time_util.py --convert "2026-03-01 14:30" --from-tz "Asia/Shanghai" --to-tz "America/New_York"
+```
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `time_util.py` | CLI tool for time queries and conversions |