ds-skills-cli 0.1.0__tar.gz

ds_skills_cli-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+*.pyc
+.DS_Store
+.claude/
+.local/
+CLAUDE.md
+PROGRESS.md

ds_skills_cli-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: ds-skills-cli
+Version: 0.1.0
+Summary: Agent-friendly CLI to browse, search, and pull data science skills from ds-skills.com
+Project-URL: Homepage, https://ds-skills.com
+Project-URL: Repository, https://github.com/wenmin-wu/ds-skills
+Project-URL: Issues, https://github.com/wenmin-wu/ds-skills/issues
+Author-email: wenmin-wu <wuwenmin1991@gmail.com>
+License-Expression: MIT
+Keywords: agent,cli,data-science,kaggle,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ds-skills-cli
+
+Agent-friendly CLI to browse, search, and pull data science skills from [ds-skills.com](https://ds-skills.com).
+
+## Install
+
+```bash
+pip install ds-skills-cli
+```
+
+## Usage
+
+```bash
+# List all skills
+ds-skills list
+ds-skills list --domain nlp
+
+# Search
+ds-skills search "deberta"
+
+# Show full skill content
+ds-skills show nlp/deberta-classification
+
+# Pull a skill to current directory
+ds-skills pull nlp/deberta-classification
+ds-skills pull nlp/deberta-classification --dest ./my-skills
+
+# Pull all skills in a domain
+ds-skills pull nlp --dest ./skills
+
+# Install to an AI agent
+ds-skills install --agent claude-code
+ds-skills install --agent cursor --domain nlp
+
+# Stats
+ds-skills stats
+```
+
+All commands support `--json` for structured output (JSON to stdout, human messages to stderr).
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Not found |
+| 3 | Invalid input |

ds_skills_cli-0.1.0/README.md

@@ -0,0 +1,48 @@
+# ds-skills-cli
+
+Agent-friendly CLI to browse, search, and pull data science skills from [ds-skills.com](https://ds-skills.com).
+
+## Install
+
+```bash
+pip install ds-skills-cli
+```
+
+## Usage
+
+```bash
+# List all skills
+ds-skills list
+ds-skills list --domain nlp
+
+# Search
+ds-skills search "deberta"
+
+# Show full skill content
+ds-skills show nlp/deberta-classification
+
+# Pull a skill to current directory
+ds-skills pull nlp/deberta-classification
+ds-skills pull nlp/deberta-classification --dest ./my-skills
+
+# Pull all skills in a domain
+ds-skills pull nlp --dest ./skills
+
+# Install to an AI agent
+ds-skills install --agent claude-code
+ds-skills install --agent cursor --domain nlp
+
+# Stats
+ds-skills stats
+```
+
+All commands support `--json` for structured output (JSON to stdout, human messages to stderr).
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Not found |
+| 3 | Invalid input |

ds_skills_cli-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ds-skills-cli"
+version = "0.1.0"
+description = "Agent-friendly CLI to browse, search, and pull data science skills from ds-skills.com"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "wenmin-wu", email = "wuwenmin1991@gmail.com" }]
+keywords = ["kaggle", "data-science", "skills", "cli", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://ds-skills.com"
+Repository = "https://github.com/wenmin-wu/ds-skills"
+Issues = "https://github.com/wenmin-wu/ds-skills/issues"
+
+[project.scripts]
+ds-skills = "ds_skills_cli.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ds_skills_cli"]

ds_skills_cli-0.1.0/src/ds_skills_cli/__init__.py

@@ -0,0 +1,3 @@
+"""ds-skills-cli: Agent-friendly CLI for ds-skills.com."""
+
+__version__ = "0.1.0"

ds_skills_cli-0.1.0/src/ds_skills_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m ds_skills_cli`."""
+
+from ds_skills_cli.cli import main
+
+main()

ds_skills_cli-0.1.0/src/ds_skills_cli/cli.py

@@ -0,0 +1,235 @@
+"""ds-skills CLI — agent-friendly interface to ds-skills.com.
+
+Exit codes: 0=success, 1=error, 2=not found, 3=invalid input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ds_skills_cli.client import ApiError, Client
+from ds_skills_cli.output import emit_json, emit_table, log
+
+# Agent install directories (default per platform)
+AGENT_DIRS = {
+    "claude-code": Path.home() / ".claude" / "skills",
+    "cursor": Path.home() / ".cursor" / "rules",
+    "codex": Path.home() / ".codex" / "skills",
+}
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    # Shared flags available on every subcommand (before or after subcommand name)
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--json", action="store_true", help="Output JSON to stdout (agent mode)"
+    )
+
+    p = argparse.ArgumentParser(
+        prog="ds-skills",
+        description="Browse, search, and pull data science skills from ds-skills.com",
+        parents=[common],
+    )
+
+    sub = p.add_subparsers(dest="command")
+
+    # --- list ---
+    ls = sub.add_parser("list", help="List skills", parents=[common])
+    ls.add_argument("--domain", "-d", help="Filter by domain")
+    ls.add_argument("--page", type=int, default=1)
+    ls.add_argument("--limit", type=int, default=200)
+
+    # --- search ---
+    sr = sub.add_parser("search", help="Search skills by keyword", parents=[common])
+    sr.add_argument("query", help="Search query")
+    sr.add_argument("--domain", "-d", help="Filter by domain")
+    sr.add_argument("--page", type=int, default=1)
+    sr.add_argument("--limit", type=int, default=50)
+
+    # --- show ---
+    sh = sub.add_parser("show", help="Show full skill detail (e.g. nlp/deberta-classification)", parents=[common])
+    sh.add_argument("skill", help="domain/slug (e.g. nlp/deberta-classification)")
+
+    # --- pull ---
+    pl = sub.add_parser("pull", help="Download and extract skills", parents=[common])
+    pl.add_argument(
+        "target",
+        help="domain/slug for one skill, or domain name for all skills in a domain",
+    )
+    pl.add_argument(
+        "--dest", "-o", type=Path, default=Path("."), help="Destination directory"
+    )
+
+    # --- install ---
+    ins = sub.add_parser("install", help="Install skills to an AI agent's skill directory", parents=[common])
+    ins.add_argument(
+        "--agent",
+        "-a",
+        required=True,
+        choices=list(AGENT_DIRS.keys()),
+        help="Target agent",
+    )
+    ins.add_argument("--domain", "-d", help="Only install skills from this domain")
+    ins.add_argument(
+        "--dest",
+        type=Path,
+        default=None,
+        help="Override default agent directory",
+    )
+
+    # --- stats ---
+    sub.add_parser("stats", help="Show aggregate statistics", parents=[common])
+
+    return p
+
+
+def _parse_skill_ref(ref: str) -> tuple[str, str | None]:
+    """Parse 'domain/slug' or 'domain'. Returns (domain, slug_or_None)."""
+    parts = ref.strip("/").split("/", 1)
+    domain = parts[0]
+    slug = parts[1] if len(parts) > 1 else None
+    return domain, slug
+
+
+def cmd_list(client: Client, args: argparse.Namespace) -> int:
+    data = client.list_skills(domain=args.domain, page=args.page, limit=args.limit)
+    if args.json:
+        emit_json(data)
+    else:
+        skills = data.get("skills", [])
+        log(f"{data.get('total', len(skills))} skills")
+        emit_table(
+            skills,
+            ["domain", "slug", "description"],
+            [12, 40, 60],
+        )
+    return 0
+
+
+def cmd_search(client: Client, args: argparse.Namespace) -> int:
+    data = client.search(
+        query=args.query, domain=args.domain, page=args.page, limit=args.limit
+    )
+    if args.json:
+        emit_json(data)
+    else:
+        results = data.get("results", [])
+        facets = data.get("facets", {})
+        log(f'{data.get("total", len(results))} results for "{args.query}"')
+        if facets:
+            log("  " + "  ".join(f"{d}:{n}" for d, n in facets.items()))
+        emit_table(results, ["domain", "slug", "description"], [12, 40, 60])
+    return 0
+
+
+def cmd_show(client: Client, args: argparse.Namespace) -> int:
+    domain, slug = _parse_skill_ref(args.skill)
+    if not slug:
+        log(f"ERROR: Invalid skill reference '{args.skill}'. Expected domain/slug.")
+        return 3
+    data = client.show_skill(domain, slug)
+    if args.json:
+        emit_json(data)
+    else:
+        print(data.get("content", ""))
+    return 0
+
+
+def cmd_pull(client: Client, args: argparse.Namespace) -> int:
+    domain, slug = _parse_skill_ref(args.target)
+    dest = args.dest
+
+    if slug:
+        log(f"Pulling {domain}/{slug} → {dest}")
+        files = client.pull_skill(domain, slug, dest)
+    else:
+        log(f"Pulling all {domain} skills → {dest}")
+        files = client.pull_domain(domain, dest)
+
+    if args.json:
+        emit_json({"files": files, "count": len(files)})
+    else:
+        log(f"{len(files)} files extracted")
+        for f in files:
+            print(f)
+    return 0
+
+
+def cmd_install(client: Client, args: argparse.Namespace) -> int:
+    dest = args.dest or AGENT_DIRS[args.agent]
+    log(f"Installing skills to {dest} (agent: {args.agent})")
+
+    if args.domain:
+        domains = [args.domain]
+    else:
+        stats = client.stats()
+        domains = list(stats.get("domains", {}).keys())
+
+    all_files: list[str] = []
+    for domain in domains:
+        log(f"  pulling {domain}...")
+        files = client.pull_domain(domain, dest)
+        all_files.extend(files)
+
+    if args.json:
+        emit_json({"agent": args.agent, "dest": str(dest), "files": all_files, "count": len(all_files)})
+    else:
+        log(f"Done. {len(all_files)} files installed to {dest}")
+    return 0
+
+
+def cmd_stats(client: Client, args: argparse.Namespace) -> int:
+    data = client.stats()
+    if args.json:
+        emit_json(data)
+    else:
+        print(f"Total skills: {data.get('total_skills', '?')}")
+        print(f"Competitions: {data.get('competitions_processed', '?')}")
+        for d, n in data.get("domains", {}).items():
+            print(f"  {d}: {n}")
+    return 0
+
+
+_DISPATCH = {
+    "list": cmd_list,
+    "search": cmd_search,
+    "show": cmd_show,
+    "pull": cmd_pull,
+    "install": cmd_install,
+    "stats": cmd_stats,
+}
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        sys.exit(3)
+
+    client = Client()
+
+    try:
+        code = _DISPATCH[args.command](client, args)
+        sys.exit(code)
+    except ApiError as exc:
+        if exc.status == 404:
+            log(f"ERROR: Not found. {exc.message}")
+            if args.json:
+                emit_json({"error": exc.message, "status": 404})
+            sys.exit(2)
+        else:
+            log(f"ERROR: {exc}")
+            if args.json:
+                emit_json({"error": str(exc), "status": exc.status})
+            sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception as exc:
+        log(f"ERROR: {exc}")
+        if args.json:
+            emit_json({"error": str(exc)})
+        sys.exit(1)

ds_skills_cli-0.1.0/src/ds_skills_cli/client.py

@@ -0,0 +1,136 @@
+"""HTTP client for the ds-skills.com API. Zero external dependencies (stdlib only)."""
+
+from __future__ import annotations
+
+import io
+import json
+import zipfile
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+BASE_URL = "https://ds-skills.com"
+_TIMEOUT = 30
+
+
+class ApiError(Exception):
+    """Raised when the API returns a non-2xx status."""
+
+    def __init__(self, status: int, message: str):
+        self.status = status
+        self.message = message
+        super().__init__(f"HTTP {status}: {message}")
+
+
+class Client:
+    """Thin wrapper around the ds-skills REST API."""
+
+    def __init__(self):
+        self.base_url = BASE_URL
+
+    # -- low-level ----------------------------------------------------------
+
+    def _get_json(self, path: str, params: dict | None = None) -> dict:
+        url = f"{self.base_url}/api{path}"
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+            if params:
+                url += "?" + urlencode(params)
+        req = Request(url, headers={"Accept": "application/json"})
+        try:
+            with urlopen(req, timeout=_TIMEOUT) as resp:
+                return json.loads(resp.read())
+        except HTTPError as exc:
+            body = exc.read().decode(errors="replace")
+            try:
+                detail = json.loads(body).get("detail", body)
+            except (json.JSONDecodeError, AttributeError):
+                detail = body
+            raise ApiError(exc.code, detail) from None
+        except URLError as exc:
+            raise ApiError(0, f"Connection failed: {exc.reason}") from None
+
+    def _get_bytes(self, path: str) -> bytes:
+        url = f"{self.base_url}/api{path}"
+        req = Request(url, headers={"Accept": "application/zip"})
+        try:
+            with urlopen(req, timeout=60) as resp:
+                return resp.read()
+        except HTTPError as exc:
+            body = exc.read().decode(errors="replace")
+            try:
+                detail = json.loads(body).get("detail", body)
+            except (json.JSONDecodeError, AttributeError):
+                detail = body
+            raise ApiError(exc.code, detail) from None
+        except URLError as exc:
+            raise ApiError(0, f"Connection failed: {exc.reason}") from None
+
+    # -- public API ---------------------------------------------------------
+
+    def list_skills(
+        self,
+        domain: str | None = None,
+        query: str | None = None,
+        page: int = 1,
+        limit: int = 200,
+    ) -> dict:
+        """GET /api/skills — list with optional domain/query filter."""
+        return self._get_json(
+            "/skills", {"domain": domain, "q": query, "page": page, "limit": limit}
+        )
+
+    def search(
+        self,
+        query: str,
+        domain: str | None = None,
+        page: int = 1,
+        limit: int = 50,
+    ) -> dict:
+        """GET /api/search — full-text search with facets."""
+        return self._get_json(
+            "/search", {"q": query, "domain": domain, "page": page, "limit": limit}
+        )
+
+    def show_skill(self, domain: str, slug: str) -> dict:
+        """GET /api/skills/{domain}/{slug} — full detail with markdown."""
+        return self._get_json(f"/skills/{domain}/{slug}")
+
+    def stats(self) -> dict:
+        """GET /api/stats — aggregate statistics."""
+        return self._get_json("/stats")
+
+    def download_skill(self, domain: str, slug: str) -> bytes:
+        """GET /api/download/{domain}/{slug} — single skill ZIP."""
+        return self._get_bytes(f"/download/{domain}/{slug}")
+
+    def download_domain(self, domain: str) -> bytes:
+        """GET /api/download/{domain} — all skills in a domain ZIP."""
+        return self._get_bytes(f"/download/{domain}")
+
+    # -- convenience --------------------------------------------------------
+
+    def pull_skill(self, domain: str, slug: str, dest: Path) -> list[str]:
+        """Download and extract a single skill. Returns list of written files."""
+        data = self.download_skill(domain, slug)
+        return self._extract_zip(data, dest)
+
+    def pull_domain(self, domain: str, dest: Path) -> list[str]:
+        """Download and extract all skills in a domain. Returns list of written files."""
+        data = self.download_domain(domain)
+        return self._extract_zip(data, dest)
+
+    @staticmethod
+    def _extract_zip(data: bytes, dest: Path) -> list[str]:
+        dest.mkdir(parents=True, exist_ok=True)
+        written: list[str] = []
+        with zipfile.ZipFile(io.BytesIO(data)) as zf:
+            for info in zf.infolist():
+                if info.is_dir():
+                    continue
+                target = dest / info.filename
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(zf.read(info))
+                written.append(str(target))
+        return written

ds_skills_cli-0.1.0/src/ds_skills_cli/output.py

@@ -0,0 +1,26 @@
+"""Structured output helpers. JSON → stdout, human → stderr."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def log(msg: str) -> None:
+    """Human-readable message to stderr (visible in both modes)."""
+    print(msg, file=sys.stderr)
+
+
+def emit_json(data: object) -> None:
+    """Machine-readable JSON to stdout."""
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def emit_table(rows: list[dict], columns: list[str], widths: list[int]) -> None:
+    """Print a simple aligned table to stdout."""
+    header = "  ".join(c.upper().ljust(w) for c, w in zip(columns, widths))
+    print(header)
+    print("-" * len(header))
+    for row in rows:
+        line = "  ".join(str(row.get(c, "")).ljust(w) for c, w in zip(columns, widths))
+        print(line)