pythonclaw 0.2.0__py3-none-any.whl

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

@@ -0,0 +1,42 @@
+---
+name: weather
+description: >
+  Get current weather and forecasts for any city or location worldwide.
+  Use when the user asks about weather, temperature, rain, wind, or
+  forecasts for any place.
+---
+
+## Instructions
+
+Fetch weather data using the **Open-Meteo API** — completely free,
+no API key required, and supports any location on Earth.
+
+### Usage
+
+```bash
+python {skill_path}/weather.py "City Name" [options]
+```
+
+Options:
+- `--forecast 3` — include N-day forecast (default: current only)
+- `--format json` — output as JSON (default: human-readable text)
+- `--units imperial` — use Fahrenheit/mph (default: metric)
+
+### Examples
+
+- "What's the weather in Tokyo?" → `python {skill_path}/weather.py "Tokyo"`
+- "5-day forecast for New York" → `python {skill_path}/weather.py "New York" --forecast 5`
+- "Is it raining in London?" → `python {skill_path}/weather.py "London"`
+- "Weather in Paris in Fahrenheit" → `python {skill_path}/weather.py "Paris" --units imperial`
+
+### How It Works
+
+1. Geocodes the city name to latitude/longitude via Open-Meteo's geocoding API
+2. Fetches current weather + optional forecast from Open-Meteo's weather API
+3. Returns temperature, humidity, wind speed, weather condition, and precipitation
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `weather.py` | Weather data fetcher via Open-Meteo |

pythonclaw/templates/skills/data/weather/weather.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Fetch weather data from Open-Meteo (free, no API key)."""
+
+import argparse
+import json
+import sys
+import urllib.request
+import urllib.parse
+
+GEOCODE_URL = "https://geocoding-api.open-meteo.com/v1/search"
+WEATHER_URL = "https://api.open-meteo.com/v1/forecast"
+
+WMO_CODES = {
+    0: "Clear sky", 1: "Mainly clear", 2: "Partly cloudy", 3: "Overcast",
+    45: "Fog", 48: "Depositing rime fog",
+    51: "Light drizzle", 53: "Moderate drizzle", 55: "Dense drizzle",
+    61: "Slight rain", 63: "Moderate rain", 65: "Heavy rain",
+    71: "Slight snow", 73: "Moderate snow", 75: "Heavy snow",
+    77: "Snow grains", 80: "Slight showers", 81: "Moderate showers",
+    82: "Violent showers", 85: "Slight snow showers", 86: "Heavy snow showers",
+    95: "Thunderstorm", 96: "Thunderstorm with slight hail",
+    99: "Thunderstorm with heavy hail",
+}
+
+
+def _fetch_json(url: str) -> dict:
+    req = urllib.request.Request(url, headers={"User-Agent": "PythonClaw/1.0"})
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        return json.loads(resp.read().decode())
+
+
+def geocode(city: str) -> dict:
+    params = urllib.parse.urlencode({"name": city, "count": 1, "language": "en"})
+    data = _fetch_json(f"{GEOCODE_URL}?{params}")
+    results = data.get("results", [])
+    if not results:
+        raise ValueError(f"Location not found: {city}")
+    r = results[0]
+    return {
+        "name": r.get("name", city),
+        "country": r.get("country", ""),
+        "lat": r["latitude"],
+        "lon": r["longitude"],
+    }
+
+
+def fetch_weather(lat: float, lon: float, forecast_days: int = 1,
+                  imperial: bool = False) -> dict:
+    temp_unit = "fahrenheit" if imperial else "celsius"
+    wind_unit = "mph" if imperial else "kmh"
+    params = {
+        "latitude": lat,
+        "longitude": lon,
+        "current": "temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m,precipitation",
+        "temperature_unit": temp_unit,
+        "wind_speed_unit": wind_unit,
+    }
+    if forecast_days > 1:
+        params["daily"] = "temperature_2m_max,temperature_2m_min,weather_code,precipitation_sum"
+        params["forecast_days"] = forecast_days
+        params["timezone"] = "auto"
+
+    qs = urllib.parse.urlencode(params)
+    return _fetch_json(f"{WEATHER_URL}?{qs}")
+
+
+def format_current(location: dict, data: dict, imperial: bool) -> str:
+    c = data.get("current", {})
+    temp = c.get("temperature_2m", "?")
+    humidity = c.get("relative_humidity_2m", "?")
+    wind = c.get("wind_speed_10m", "?")
+    precip = c.get("precipitation", 0)
+    code = c.get("weather_code", 0)
+    condition = WMO_CODES.get(code, f"Code {code}")
+
+    t_unit = "F" if imperial else "C"
+    w_unit = "mph" if imperial else "km/h"
+
+    lines = [
+        f"Weather in {location['name']}, {location['country']}",
+        f"  Condition: {condition}",
+        f"  Temperature: {temp}°{t_unit}",
+        f"  Humidity: {humidity}%",
+        f"  Wind: {wind} {w_unit}",
+    ]
+    if precip > 0:
+        lines.append(f"  Precipitation: {precip} mm")
+    return "\n".join(lines)
+
+
+def format_forecast(data: dict, imperial: bool) -> str:
+    daily = data.get("daily", {})
+    dates = daily.get("time", [])
+    if not dates:
+        return ""
+
+    t_unit = "F" if imperial else "C"
+    lines = ["\nForecast:"]
+    for i, date in enumerate(dates):
+        hi = daily["temperature_2m_max"][i]
+        lo = daily["temperature_2m_min"][i]
+        code = daily["weather_code"][i]
+        precip = daily["precipitation_sum"][i]
+        condition = WMO_CODES.get(code, f"Code {code}")
+        line = f"  {date}: {lo}–{hi}°{t_unit}  {condition}"
+        if precip > 0:
+            line += f"  (precip: {precip}mm)"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Get weather for any location.")
+    parser.add_argument("city", help="City name (e.g. 'Tokyo', 'New York')")
+    parser.add_argument("--forecast", type=int, default=1,
+                        help="Number of forecast days (default: current only)")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--units", choices=["metric", "imperial"], default="metric")
+    args = parser.parse_args()
+
+    imperial = args.units == "imperial"
+
+    try:
+        loc = geocode(args.city)
+        data = fetch_weather(loc["lat"], loc["lon"],
+                             forecast_days=max(args.forecast, 1),
+                             imperial=imperial)
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.format == "json":
+        data["location"] = loc
+        print(json.dumps(data, indent=2))
+    else:
+        print(format_current(loc, data, imperial))
+        if args.forecast > 1:
+            print(format_forecast(data, imperial))
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,43 @@
+---
+name: youtube
+description: >
+  Get YouTube video information, metadata, and transcripts/subtitles.
+  Use when the user asks about a YouTube video, wants a video summary,
+  needs a transcript, or asks to extract info from a YouTube URL.
+---
+
+## Instructions
+
+Extract information and transcripts from YouTube videos.
+
+### Prerequisites
+
+Install dependencies: `pip install yt-dlp youtube-transcript-api`
+
+### Usage
+
+```bash
+python {skill_path}/youtube_info.py URL [command] [options]
+```
+
+Commands:
+- `info` (default) — video title, duration, views, description
+- `transcript` — full transcript/subtitles
+- `search` — search YouTube for videos (uses URL arg as search query)
+
+Options:
+- `--lang en` — transcript language (default: en)
+- `--format json` — output as JSON
+- `--max 5` — max results for search (default: 5)
+
+### Examples
+
+- "What's this video about? https://youtube.com/watch?v=xyz" → `youtube_info.py URL info`
+- "Get the transcript of this video" → `youtube_info.py URL transcript`
+- "Search YouTube for Python tutorials" → `youtube_info.py "Python tutorials" search`
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `youtube_info.py` | YouTube info and transcript extractor |

pythonclaw/templates/skills/data/youtube/youtube_info.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Extract YouTube video info and transcripts."""
+
+import argparse
+import json
+import sys
+
+
+def _try_import(pkg, install_name):
+    try:
+        return __import__(pkg)
+    except ImportError:
+        print(f"Error: {install_name} not installed.  Run: pip install {install_name}",
+              file=sys.stderr)
+        sys.exit(1)
+
+
+def get_info(url: str) -> dict:
+    yt_dlp = _try_import("yt_dlp", "yt-dlp")
+    opts = {
+        "quiet": True,
+        "no_warnings": True,
+        "skip_download": True,
+    }
+    with yt_dlp.YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=False)
+
+    return {
+        "title": info.get("title", ""),
+        "channel": info.get("uploader", ""),
+        "duration": info.get("duration", 0),
+        "durationFormatted": _format_duration(info.get("duration", 0)),
+        "views": info.get("view_count", 0),
+        "likes": info.get("like_count"),
+        "uploadDate": info.get("upload_date", ""),
+        "description": (info.get("description") or "")[:1000],
+        "url": info.get("webpage_url", url),
+        "thumbnail": info.get("thumbnail", ""),
+    }
+
+
+def get_transcript(url: str, lang: str = "en") -> list[dict]:
+    _try_import("yt_dlp", "yt-dlp")
+    ytt = _try_import("youtube_transcript_api", "youtube-transcript-api")
+
+    video_id = _extract_video_id(url)
+    if not video_id:
+        raise ValueError(f"Could not extract video ID from: {url}")
+
+    api = ytt.YouTubeTranscriptApi()
+    try:
+        transcript = api.fetch(video_id, languages=[lang])
+    except Exception:
+        transcript = api.fetch(video_id)
+
+    return [
+        {
+            "start": round(entry.start, 1),
+            "duration": round(entry.duration, 1),
+            "text": entry.text,
+        }
+        for entry in transcript
+    ]
+
+
+def search_youtube(query: str, max_results: int = 5) -> list[dict]:
+    yt_dlp = _try_import("yt_dlp", "yt-dlp")
+    opts = {
+        "quiet": True,
+        "no_warnings": True,
+        "skip_download": True,
+        "extract_flat": True,
+        "playlist_items": f"1:{max_results}",
+    }
+    with yt_dlp.YoutubeDL(opts) as ydl:
+        result = ydl.extract_info(f"ytsearch{max_results}:{query}", download=False)
+
+    entries = result.get("entries", [])
+    return [
+        {
+            "title": e.get("title", ""),
+            "url": e.get("url", ""),
+            "channel": e.get("uploader", e.get("channel", "")),
+            "duration": e.get("duration"),
+        }
+        for e in entries
+    ]
+
+
+def _extract_video_id(url: str) -> str | None:
+    import re
+    patterns = [
+        r"(?:v=|/v/|youtu\.be/)([a-zA-Z0-9_-]{11})",
+        r"^([a-zA-Z0-9_-]{11})$",
+    ]
+    for p in patterns:
+        m = re.search(p, url)
+        if m:
+            return m.group(1)
+    return None
+
+
+def _format_duration(seconds: int) -> str:
+    if not seconds:
+        return "N/A"
+    h, remainder = divmod(seconds, 3600)
+    m, s = divmod(remainder, 60)
+    if h:
+        return f"{h}:{m:02d}:{s:02d}"
+    return f"{m}:{s:02d}"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="YouTube video info & transcripts.")
+    parser.add_argument("url", help="YouTube URL or search query")
+    parser.add_argument("command", nargs="?", default="info",
+                        choices=["info", "transcript", "search"])
+    parser.add_argument("--lang", default="en", help="Transcript language")
+    parser.add_argument("--max", type=int, default=5, help="Max search results")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    args = parser.parse_args()
+
+    try:
+        if args.command == "info":
+            data = get_info(args.url)
+            if args.format == "json":
+                print(json.dumps(data, indent=2, ensure_ascii=False))
+            else:
+                print(f"Title: {data['title']}")
+                print(f"Channel: {data['channel']}")
+                print(f"Duration: {data['durationFormatted']}")
+                print(f"Views: {data['views']:,}")
+                if data["likes"]:
+                    print(f"Likes: {data['likes']:,}")
+                print(f"Uploaded: {data['uploadDate']}")
+                print(f"URL: {data['url']}")
+                if data["description"]:
+                    print(f"\nDescription:\n{data['description']}")
+
+        elif args.command == "transcript":
+            entries = get_transcript(args.url, lang=args.lang)
+            if args.format == "json":
+                print(json.dumps(entries, indent=2, ensure_ascii=False))
+            else:
+                for e in entries:
+                    ts = _format_duration(int(e["start"]))
+                    print(f"[{ts}] {e['text']}")
+
+        elif args.command == "search":
+            results = search_youtube(args.url, max_results=args.max)
+            if args.format == "json":
+                print(json.dumps(results, indent=2, ensure_ascii=False))
+            else:
+                for i, r in enumerate(results, 1):
+                    dur = _format_duration(r["duration"]) if r["duration"] else "?"
+                    print(f"{i}. {r['title']}  [{dur}]")
+                    print(f"   {r['channel']}")
+                    print(f"   {r['url']}")
+                    print()
+
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

pythonclaw/templates/skills/dev/CATEGORY.md

@@ -0,0 +1,4 @@
+---
+name: dev
+description: Developer tools — HTTP requests, GitHub integration, and other dev utilities.
+---

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

@@ -0,0 +1,46 @@
+---
+name: code_runner
+description: >
+  Execute Python code snippets safely in an isolated subprocess with
+  timeout protection. Use when the user asks to run, test, or evaluate
+  Python code, calculate expressions, or prototype logic.
+---
+
+## Instructions
+
+Run Python code in an isolated subprocess with stdout/stderr capture
+and timeout protection. No extra dependencies needed.
+
+### Usage
+
+```bash
+python {skill_path}/run_code.py [options]
+```
+
+Input methods:
+- `--code "print(2+2)"` — inline code string
+- `--file script.py` — run a Python file
+- `stdin` — pipe code via stdin
+
+Options:
+- `--timeout 30` — max execution time in seconds (default: 30)
+- `--format json` — output as JSON with stdout, stderr, exit code
+- `--no-capture` — stream output directly (no capture)
+
+### Examples
+
+- "Calculate 2^100" → `run_code.py --code "print(2**100)"`
+- "Run this Python snippet" → `run_code.py --code "import math; print(math.pi)"`
+- "Test this function" → `run_code.py --file test.py`
+
+### Security
+
+- Code runs in a **subprocess** (not eval/exec in the agent process)
+- Timeout prevents infinite loops
+- Working directory is the project root
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `run_code.py` | Safe Python code executor |

pythonclaw/templates/skills/dev/code_runner/run_code.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Execute Python code in an isolated subprocess with timeout."""
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+import os
+
+
+def run_code(code: str, timeout: int = 30, cwd: str | None = None) -> dict:
+    """Run Python code in a subprocess and capture output."""
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".py", delete=False, encoding="utf-8"
+    ) as f:
+        f.write(code)
+        tmp_path = f.name
+
+    try:
+        python = sys.executable
+        result = subprocess.run(
+            [python, tmp_path],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=cwd,
+        )
+        return {
+            "exitCode": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+            "timedOut": False,
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "exitCode": -1,
+            "stdout": "",
+            "stderr": f"Execution timed out after {timeout}s",
+            "timedOut": True,
+        }
+    except Exception as exc:
+        return {
+            "exitCode": -1,
+            "stdout": "",
+            "stderr": str(exc),
+            "timedOut": False,
+        }
+    finally:
+        os.unlink(tmp_path)
+
+
+def run_file(path: str, timeout: int = 30) -> dict:
+    """Run a Python file in a subprocess."""
+    try:
+        python = sys.executable
+        result = subprocess.run(
+            [python, path],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        return {
+            "exitCode": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+            "timedOut": False,
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "exitCode": -1,
+            "stdout": "",
+            "stderr": f"Execution timed out after {timeout}s",
+            "timedOut": True,
+        }
+    except Exception as exc:
+        return {
+            "exitCode": -1,
+            "stdout": "",
+            "stderr": str(exc),
+            "timedOut": False,
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Execute Python code safely.")
+    parser.add_argument("--code", default=None, help="Python code to execute")
+    parser.add_argument("--file", default=None, help="Python file to execute")
+    parser.add_argument("--timeout", type=int, default=30, help="Timeout in seconds")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    args = parser.parse_args()
+
+    if args.file:
+        result = run_file(args.file, timeout=args.timeout)
+    elif args.code:
+        result = run_code(args.code, timeout=args.timeout)
+    elif not sys.stdin.isatty():
+        code = sys.stdin.read()
+        result = run_code(code, timeout=args.timeout)
+    else:
+        parser.error("Provide --code, --file, or pipe code via stdin.")
+        return
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        if result["stdout"]:
+            print(result["stdout"], end="")
+        if result["stderr"]:
+            print(result["stderr"], end="", file=sys.stderr)
+        if result["timedOut"]:
+            print(f"\n[Timed out after {args.timeout}s]", file=sys.stderr)
+        sys.exit(result["exitCode"])
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,52 @@
+---
+name: github
+description: >
+  Interact with the GitHub API — list repos, create issues, view PRs,
+  manage releases. Use when the user asks about GitHub repositories,
+  issues, pull requests, or wants to perform any GitHub operation.
+  Requires a GitHub Personal Access Token in pythonclaw.json.
+---
+
+## Instructions
+
+Interact with the GitHub REST API.  A Personal Access Token (PAT) is
+read from `skills.github.token` in `pythonclaw.json`.
+
+### Prerequisites
+
+1. Create a PAT at https://github.com/settings/tokens
+2. Configure in `pythonclaw.json`:
+
+```json
+"skills": {
+  "github": {
+    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+  }
+}
+```
+
+### Usage
+
+```bash
+python {skill_path}/gh.py <command> [options]
+```
+
+Commands:
+- `repos <user>` — list user's public repositories
+- `repo <owner/repo>` — get repository details
+- `issues <owner/repo>` — list open issues
+- `create-issue <owner/repo> --title "..." --body "..."` — create an issue
+- `prs <owner/repo>` — list open pull requests
+- `pr <owner/repo> <number>` — get PR details
+
+### Examples
+
+- "List my GitHub repositories" → `gh.py repos <username>`
+- "Show open issues on pythonclaw" → `gh.py issues user/pythonclaw`
+- "Create an issue for the login bug" → `gh.py create-issue user/repo --title "Login bug" --body "..."`
+
+## Resources
+
+| File | Description |
+|------|-------------|
+| `gh.py` | GitHub API client |