pythonclaw 0.2.0__py3-none-any.whl

pythonclaw/templates/skills/dev/github/gh.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""GitHub API client.  Reads token from pythonclaw.json."""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+try:
+    import requests
+except ImportError:
+    print("Error: requests not installed.  Run: pip install requests", file=sys.stderr)
+    sys.exit(1)
+
+API = "https://api.github.com"
+
+
+def _load_token() -> str:
+    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)
+        token = data.get("skills", {}).get("github", {}).get("token", "")
+        if token:
+            return token
+    return ""
+
+
+def _headers() -> dict:
+    token = _load_token()
+    h = {"Accept": "application/vnd.github+json"}
+    if token:
+        h["Authorization"] = f"Bearer {token}"
+    return h
+
+
+def _get(path: str) -> dict | list:
+    resp = requests.get(f"{API}{path}", headers=_headers(), timeout=30)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _post(path: str, body: dict) -> dict:
+    resp = requests.post(f"{API}{path}", headers=_headers(), json=body, timeout=30)
+    resp.raise_for_status()
+    return resp.json()
+
+
+def cmd_repos(user: str) -> None:
+    repos = _get(f"/users/{user}/repos?sort=updated&per_page=30")
+    for r in repos:
+        stars = r.get("stargazers_count", 0)
+        lang = r.get("language", "")
+        desc = r.get("description", "") or ""
+        print(f"  {r['full_name']}  [{lang}]  \u2605{stars}")
+        if desc:
+            print(f"    {desc[:100]}")
+
+
+def cmd_repo(full_name: str) -> None:
+    r = _get(f"/repos/{full_name}")
+    print(json.dumps({
+        "name": r["full_name"],
+        "description": r.get("description", ""),
+        "language": r.get("language"),
+        "stars": r["stargazers_count"],
+        "forks": r["forks_count"],
+        "open_issues": r["open_issues_count"],
+        "url": r["html_url"],
+        "created": r["created_at"],
+        "updated": r["updated_at"],
+    }, indent=2))
+
+
+def cmd_issues(full_name: str) -> None:
+    issues = _get(f"/repos/{full_name}/issues?state=open&per_page=30")
+    for i in issues:
+        if i.get("pull_request"):
+            continue
+        labels = ", ".join(lb["name"] for lb in i.get("labels", []))
+        print(f"  #{i['number']}  {i['title']}")
+        if labels:
+            print(f"    Labels: {labels}")
+
+
+def cmd_create_issue(full_name: str, title: str, body: str) -> None:
+    result = _post(f"/repos/{full_name}/issues", {"title": title, "body": body})
+    print(f"Created issue #{result['number']}: {result['html_url']}")
+
+
+def cmd_prs(full_name: str) -> None:
+    prs = _get(f"/repos/{full_name}/pulls?state=open&per_page=30")
+    for pr in prs:
+        print(f"  #{pr['number']}  {pr['title']}  ({pr['user']['login']})")
+
+
+def cmd_pr(full_name: str, number: int) -> None:
+    pr = _get(f"/repos/{full_name}/pulls/{number}")
+    print(json.dumps({
+        "number": pr["number"],
+        "title": pr["title"],
+        "state": pr["state"],
+        "author": pr["user"]["login"],
+        "branch": pr["head"]["ref"],
+        "base": pr["base"]["ref"],
+        "body": (pr.get("body") or "")[:500],
+        "url": pr["html_url"],
+        "mergeable": pr.get("mergeable"),
+    }, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="GitHub API client.")
+    sub = parser.add_subparsers(dest="command")
+
+    p_repos = sub.add_parser("repos")
+    p_repos.add_argument("user")
+
+    p_repo = sub.add_parser("repo")
+    p_repo.add_argument("full_name", help="owner/repo")
+
+    p_issues = sub.add_parser("issues")
+    p_issues.add_argument("full_name", help="owner/repo")
+
+    p_ci = sub.add_parser("create-issue")
+    p_ci.add_argument("full_name", help="owner/repo")
+    p_ci.add_argument("--title", required=True)
+    p_ci.add_argument("--body", default="")
+
+    p_prs = sub.add_parser("prs")
+    p_prs.add_argument("full_name", help="owner/repo")
+
+    p_pr = sub.add_parser("pr")
+    p_pr.add_argument("full_name", help="owner/repo")
+    p_pr.add_argument("number", type=int)
+
+    args = parser.parse_args()
+
+    try:
+        if args.command == "repos":
+            cmd_repos(args.user)
+        elif args.command == "repo":
+            cmd_repo(args.full_name)
+        elif args.command == "issues":
+            cmd_issues(args.full_name)
+        elif args.command == "create-issue":
+            cmd_create_issue(args.full_name, args.title, args.body)
+        elif args.command == "prs":
+            cmd_prs(args.full_name)
+        elif args.command == "pr":
+            cmd_pr(args.full_name, args.number)
+        else:
+            parser.print_help()
+    except requests.HTTPError as exc:
+        print(f"GitHub API error: {exc.response.status_code} {exc.response.text[:200]}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pythonclaw/templates/skills/dev/http_request/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: http_request
+description: >
+  Make HTTP requests (GET, POST, PUT, DELETE, PATCH) to any API endpoint.
+  Use when the user asks to call an API, test an endpoint, fetch JSON data
+  from a URL, or interact with a REST API.
+---
+
+## Instructions
+
+Make arbitrary HTTP requests to any API endpoint.
+
+### Prerequisites
+
+Install dependency: `pip install requests`
+
+### Usage
+
+```bash
+python {skill_path}/request.py URL [options]
+```
+
+Options:
+- `--method GET|POST|PUT|DELETE|PATCH` (default: GET)
+- `--data '{"key": "value"}'` — JSON request body
+- `--header "Name: Value"` — custom header (repeatable)
+- `--timeout 30` — timeout in seconds
+- `--format text|json|headers` — output format
+
+### Examples
+
+- "GET https://api.github.com/users/octocat"
+- "POST to https://httpbin.org/post with body {'name': 'test'}"
+- "Call the weather API at https://api.example.com/weather?city=Tokyo"
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `request.py` | Generic HTTP request tool |

pythonclaw/templates/skills/dev/http_request/request.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Make arbitrary HTTP requests to any API endpoint."""
+
+import argparse
+import json
+import sys
+
+try:
+    import requests
+except ImportError:
+    print("Error: requests not installed.  Run: pip install requests", file=sys.stderr)
+    sys.exit(1)
+
+
+def http_request(
+    url: str,
+    method: str = "GET",
+    data: str | None = None,
+    headers: dict | None = None,
+    timeout: int = 30,
+) -> dict:
+    headers = headers or {}
+    body = None
+    if data:
+        try:
+            body = json.loads(data)
+            headers.setdefault("Content-Type", "application/json")
+        except json.JSONDecodeError:
+            body = data
+
+    resp = requests.request(
+        method=method.upper(),
+        url=url,
+        json=body if isinstance(body, (dict, list)) else None,
+        data=body if isinstance(body, str) else None,
+        headers=headers,
+        timeout=timeout,
+    )
+
+    try:
+        resp_body = resp.json()
+    except Exception:
+        resp_body = resp.text[:5000]
+
+    return {
+        "status": resp.status_code,
+        "headers": dict(resp.headers),
+        "body": resp_body,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Make HTTP requests.")
+    parser.add_argument("url", help="Request URL")
+    parser.add_argument("--method", default="GET", choices=["GET", "POST", "PUT", "DELETE", "PATCH"])
+    parser.add_argument("--data", default=None, help="Request body (JSON string)")
+    parser.add_argument("--header", action="append", default=[], help="Header in 'Name: Value' format")
+    parser.add_argument("--timeout", type=int, default=30)
+    parser.add_argument("--format", choices=["text", "json", "headers"], default="text")
+    args = parser.parse_args()
+
+    headers = {}
+    for h in args.header:
+        if ":" in h:
+            k, v = h.split(":", 1)
+            headers[k.strip()] = v.strip()
+
+    try:
+        result = http_request(args.url, args.method, args.data, headers, args.timeout)
+    except Exception as exc:
+        print(f"Request failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    elif args.format == "headers":
+        print(f"Status: {result['status']}")
+        for k, v in result["headers"].items():
+            print(f"  {k}: {v}")
+    else:
+        print(f"Status: {result['status']}")
+        body = result["body"]
+        if isinstance(body, (dict, list)):
+            print(json.dumps(body, indent=2, ensure_ascii=False))
+        else:
+            print(body)
+
+
+if __name__ == "__main__":
+    main()

pythonclaw/templates/skills/google/CATEGORY.md

@@ -0,0 +1,4 @@
+---
+name: google
+description: Google Workspace skills — Gmail, Calendar, Drive, Contacts, Sheets, Docs via the gog CLI.
+---

pythonclaw/templates/skills/google/workspace/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: google_workspace
+description: >
+  Google Workspace CLI — Gmail, Calendar, Drive, Contacts, Sheets, and Docs
+  via the gog command-line tool. Use when the user asks to send email, search
+  Gmail, check calendar events, manage Google Drive files, read or edit
+  Google Sheets, export Google Docs, or look up contacts.
+---
+# Google Workspace (gog CLI)
+
+Powered by [gog](https://github.com/steipete/gogcli) — a Google Workspace
+CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
+
+## Prerequisites
+
+Install gog:
+```
+brew install steipete/tap/gogcli
+```
+
+On Linux (manual install):
+```
+curl -fsSL https://api.github.com/repos/steipete/gogcli/releases/latest \
+  | grep browser_download_url | grep linux_amd64
+# Download the tarball, extract, and install:
+# sudo install -m 0755 gog /usr/local/bin/gog
+```
+
+## Setup (one-time)
+
+1. Create OAuth credentials at [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
+   (Desktop App type) and download `client_secret.json`.
+2. Run:
+```
+gog auth credentials /path/to/client_secret.json
+gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,docs
+```
+3. Optionally set `GOG_ACCOUNT=you@gmail.com` as an environment variable to avoid `--account` on every call.
+
+## Commands
+
+### Gmail
+
+| Action | Command |
+|--------|---------|
+| Search mail | `gog gmail search 'newer_than:7d' --max 10` |
+| Send email | `gog gmail send --to user@example.com --subject "Hi" --body "Hello"` |
+| Read message | `gog gmail read <message_id>` |
+| Mark as read | `gog gmail labels modify <message_id> --remove UNREAD` |
+| List labels | `gog gmail labels list` |
+
+### Calendar
+
+| Action | Command |
+|--------|---------|
+| List events | `gog calendar events --from 2026-02-23 --to 2026-02-28` |
+| Create event | `gog calendar create --title "Meeting" --start "2026-02-24T10:00" --end "2026-02-24T11:00"` |
+
+### Drive
+
+| Action | Command |
+|--------|---------|
+| Search files | `gog drive search "query" --max 10` |
+| List files | `gog drive list --max 20` |
+| Download | `gog drive download <file_id> --out /tmp/file.pdf` |
+
+### Google Sheets
+
+| Action | Command |
+|--------|---------|
+| Get data | `gog sheets get <spreadsheet_id> "Sheet1!A1:D10" --json` |
+| Metadata | `gog sheets metadata <spreadsheet_id> --json` |
+| Append rows | `gog sheets append <spreadsheet_id> "Sheet1!A:C" --values-json '[["x","y","z"]]' --insert I...
+| Update cells | `gog sheets update <spreadsheet_id> "Sheet1!A1:B2" --values-json '[["A","B"],["1","2"]]' -...
+| Clear range | `gog sheets clear <spreadsheet_id> "Sheet1!A2:Z"` |
+
+### Google Docs
+
+| Action | Command |
+|--------|---------|
+| Read content | `gog docs cat <document_id>` |
+| Export | `gog docs export <document_id> --format txt --out /tmp/doc.txt` |
+| Copy | `gog docs copy <document_id> --title "Copy of Doc"` |
+
+### Contacts
+
+| Action | Command |
+|--------|---------|
+| List contacts | `gog contacts list --max 20` |
+| Search | `gog contacts search "name"` |
+
+## Important Notes
+
+- **Always confirm** before sending emails or creating calendar events.
+- For scripting/automation, prefer `--json` and `--no-input` flags.
+- Google Docs in-place editing requires the Docs API directly (not available in gog).
+- Set `GOG_ACCOUNT` env var to skip `--account` on every command.
+- Use `gog auth list` to check configured accounts.

pythonclaw/templates/skills/google/workspace/check_setup.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Pre-activation check for the Google Workspace (gog) skill.
+# Exit 0 = ready, exit 1 = not ready (output tells the user what to fix).
+
+set -euo pipefail
+
+# ?? 1. Is gog installed? ??????????????????????????????????????????????????????
+if ! command -v gog &>/dev/null; then
+    cat <<'EOF'
+ERROR: The 'gog' CLI is not installed.
+
+To install on macOS:
+  brew install steipete/tap/gogcli
+
+To install on Linux:
+  curl -fsSL https://api.github.com/repos/steipete/gogcli/releases/latest \
+    | grep browser_download_url | grep linux_amd64
+  # Download the tarball, extract, then: sudo install -m 0755 gog /usr/local/bin/gog
+
+More info: https://github.com/steipete/gogcli
+EOF
+    exit 1
+fi
+
+echo "gog version: $(gog --version 2>/dev/null || echo 'unknown')"
+
+# ?? 2. Is at least one account configured? ????????????????????????????????????
+AUTH_OUTPUT=$(gog auth list 2>&1)
+if echo "$AUTH_OUTPUT" | grep -qi "no tokens"; then
+    cat <<'EOF'
+
+ERROR: No Google account is configured in gog.
+
+Setup steps:
+  1. Go to https://console.cloud.google.com/apis/credentials
+  2. Create an OAuth 2.0 Client ID (Desktop App type)
+  3. Download the client_secret.json file
+  4. Run:
+       gog auth credentials /path/to/client_secret.json
+       gog auth add you@gmail.com --services gmail,calendar,drive,contacts,sheets,docs
+  5. A browser window will open ? authorize the app.
+
+After setup, try again.
+EOF
+    exit 1
+fi
+
+echo ""
+echo "Configured accounts:"
+echo "$AUTH_OUTPUT"
+echo ""
+echo "Ready to use Google Workspace commands."

pythonclaw/templates/skills/meta/CATEGORY.md

@@ -0,0 +1,4 @@
+---
+name: meta
+description: Meta-skills that extend the agent's own capabilities at runtime.
+---

pythonclaw/templates/skills/meta/skill_creator/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: skill_creator
+description: >
+  Dynamically create new skills when no existing skill can handle the user's
+  request. Use this when you need a capability that doesn't exist yet —
+  write the code, bundle it as a skill, install dependencies, and make it
+  immediately available.
+---
+
+## Instructions
+
+You have the ability to **create brand-new skills on the fly** using the
+`create_skill` tool. This is your "god mode" — if no existing skill can
+fulfill a request, design and build one yourself.
+
+### When to Use
+
+- The user asks for something none of the installed skills cover
+- An existing skill is too limited and a better replacement is needed
+- A recurring task would benefit from a dedicated, reusable skill
+
+### When NOT to Use
+
+- **DON'T** create a skill for a one-off task that existing tools can handle
+  (e.g. `run_command` can already execute shell commands)
+- **DON'T** create a skill that's too specific to be reused — always think
+  about what the **general category** of the request is and build for that
+- **DON'T** hardcode user-specific values (names, URLs, topics) into the
+  skill — make them parameters
+
+### Design Principles
+
+1. **GENERIC over specific** — NEVER create a skill that only works for
+   one narrow task. Always generalize:
+   - BAD: `us_iran_news_fetcher` (hardcoded topic, useless for anything else)
+   - GOOD: `news` (searches any topic, parameterized query)
+   - BAD: `send_meeting_invite_to_bob` (single use case)
+   - GOOD: `email` (sends any email to any recipient)
+2. **Parameterized** — use command-line arguments, not hardcoded values.
+   Every specific detail (query, recipient, URL, etc.) should be an argument.
+3. **Single Responsibility** — each skill should do one thing well
+4. **Clean Code** — write production-quality Python scripts with proper
+   error handling, logging, and docstrings
+5. **Minimal Dependencies** — only add pip packages that are truly needed
+6. **Clear Instructions** — the SKILL.md body should explain exactly how
+   to use the skill so your future self (or another agent) can follow it
+7. **Reusable** — design the skill to work for ANY similar future request.
+   Ask yourself: "Would this skill be useful to someone with a completely
+   different task?" If not, generalize it.
+8. **Config-driven credentials** — if the skill needs API keys or tokens,
+   read them from `pythonclaw.json` (under `skills.<name>`) instead of
+   hardcoding or requiring environment variables
+
+### Step-by-Step Workflow
+
+1. **Analyze the gap**: identify exactly what capability is missing
+2. **Plan the skill**: decide on the name, category, required scripts,
+   and any pip dependencies
+3. **Call `create_skill`** with:
+   - `name` — short, descriptive, snake_case (e.g. `pdf_summarizer`)
+   - `description` — one-line summary for the skill catalog
+   - `instructions` — full Markdown body (see template below)
+   - `category` — group folder (e.g. `data`, `dev`, `web`, `automation`)
+   - `resources` — dict mapping filenames to their source code
+   - `dependencies` — list of pip packages to install
+4. **Activate the skill**: call `use_skill(skill_name="<name>")` to load
+   the new instructions
+5. **Run it**: follow the loaded instructions to execute the task
+
+### SKILL.md Body Template
+
+Use this structure for the `instructions` argument:
+
+```
+## Instructions
+
+<Clear explanation of what the skill does and when to use it.>
+
+### Prerequisites
+
+- <any setup steps or API keys needed>
+
+### Usage
+
+1. <step-by-step usage instructions>
+2. Call `run_command` with: `python context/skills/<category>/<name>/<script>.py <args>`
+3. <interpret results>
+
+### Examples
+
+**Example:** <describe a typical use case>
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `script.py` | <what it does> |
+```
+
+### Resource Script Template
+
+When writing Python scripts for `resources`, follow this pattern:
+
+```python
+#!/usr/bin/env python3
+"""One-line description of the script."""
+import argparse
+import json
+import sys
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", help="Input to process")
+    parser.add_argument("--format", default="text", choices=["text", "json"])
+    args = parser.parse_args()
+
+    try:
+        result = process(args.input)
+        if args.format == "json":
+            print(json.dumps(result, indent=2))
+        else:
+            print(result)
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+def process(data):
+    # ... actual logic ...
+    return data
+
+if __name__ == "__main__":
+    main()
+```
+
+### Example: Creating a CSV Analyzer Skill
+
+```
+create_skill(
+    name="csv_analyzer",
+    description="Analyze CSV files — summary statistics, column info, and data preview.",
+    category="data",
+    instructions="## Instructions\n\nAnalyze CSV files ...",
+    resources={
+        "analyze.py": "#!/usr/bin/env python3\nimport pandas as pd\n..."
+    },
+    dependencies=["pandas"]
+)
+```
+
+After creation, call `use_skill(skill_name="csv_analyzer")` to activate it,
+then follow its instructions.

pythonclaw/templates/skills/system/CATEGORY.md

@@ -0,0 +1,4 @@
+---
+name: system
+description: Agent self-management — onboarding, identity, and configuration.
+---

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

@@ -0,0 +1,41 @@
+---
+name: change_persona
+description: >
+  Modify the agent's personality and role (persona.md). Use when the user
+  wants to change the agent's personality, communication style, focus area,
+  or specialization.
+---
+
+## Instructions
+
+Modify the agent's persona file at `context/persona/persona.md`.
+
+### When to Use
+
+- User says "be more formal", "be funnier", "focus on finance now"
+- User wants to change the agent's specialization or expertise area
+- User asks to adjust communication style or personality traits
+
+### How to Use
+
+1. Ask the user what they want to change
+2. Read the current persona file:
+   ```
+   read_file("context/persona/persona.md")
+   ```
+3. Modify the relevant section and write it back:
+   ```
+   write_file("context/persona/persona.md", "...updated content...")
+   ```
+4. Tell the user: "Persona 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 persona.md
+- Only change the specific section the user asked about
+- If the file doesn't exist yet, create it with a reasonable template
+
+## Resources
+
+This skill uses the built-in `read_file` and `write_file` tools directly.