Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
| """Generate and install the pwc CLI skill for AI coding agents.""" | |
| from __future__ import annotations | |
| import argparse | |
| import os | |
| import shutil | |
| import tempfile | |
| from pathlib import Path | |
| from pwc_cli import __version__ | |
| SKILL_NAME = "pwc-cli" | |
| CENTRAL_LOCAL = Path(".agents/skills") | |
| CENTRAL_GLOBAL = Path("~/.agents/skills") | |
| CLAUDE_LOCAL = Path(".claude/skills") | |
| CLAUDE_GLOBAL = Path("~/.claude/skills") | |
| _DESCRIPTION = ( | |
| "Papers With Code CLI (`pwc`) for searching and reading AI/ML papers, " | |
| "discovering recent and trending research, finding related work and paper " | |
| "lineage, browsing tasks, methods, conferences, organizations, frameworks, " | |
| "and benchmark leaderboards, and submitting authenticated paper edits " | |
| "through the public Papers With Code catalog. Use whenever the user asks to " | |
| "find papers, survey literature, compare research, inspect an arXiv paper, " | |
| "explore AI/ML taxonomy or conferences, discover benchmarks or " | |
| "state-of-the-art models, or mentions Papers With Code, `pwc`, or `pwc-cli`." | |
| ) | |
| _INTRODUCTION = """ | |
| Research commands query the public [Papers With Code](https://paperswithcode.co) catalog anonymously. | |
| Paper editing requires explicit browser authorization through `pwc auth login --paper PAPER`. | |
| Run `pwc --help` or a nested `--help` command when the live parser and this | |
| skill disagree; the parser is authoritative. | |
| Use compact output for reading and discovery. Add `--json` for programmatic | |
| filtering, joining, or schema-dependent processing. | |
| When the user identifies an author, prefer repeatable structured | |
| `pwc paper list --author AUTHOR` filters. Add `--search TEXT` for stated topic | |
| terms and explicit `--order-by date_published --order-dir desc` for newest or | |
| recent work. Author references accept an exact normalized name, numeric ID, or | |
| `@HF_USERNAME`; repeated authors use AND semantics. | |
| Publication date ranges are inclusive: use `--start-date YYYY-MM-DD` and | |
| `--end-date YYYY-MM-DD` with `pwc search` or `pwc paper list`; the start date | |
| must not be later than `--end-date`. The combined flags are | |
| `--start-date YYYY-MM-DD --end-date YYYY-MM-DD`. | |
| Paper discovery commands accept `--implementation-coverage` to add official | |
| implementation status and total linked repository count columns. JSON and | |
| `pwc paper info` always include both fields. Use | |
| `--has-official-implementation` with `pwc search` or `pwc paper list` to require | |
| a catalog-linked official repository; these filters fail closed if unconfirmed. | |
| Use `pwc benchmark --name NAME --max-parameters SIZE` to keep models at or | |
| below an inclusive parameter limit. SIZE accepts values such as `500M`, `1.5B`, | |
| `3B`, and raw integers. Models without one consistent parameter count are | |
| excluded from constrained results. | |
| `PAPER` accepts a modern or legacy arXiv ID, a numeric external-paper ID, or an | |
| exact paper title. Quote titles containing spaces. Title matching is | |
| case-insensitive but exact; ambiguous titles fail with their matching IDs. | |
| When `pwc paper info` or `pwc paper read` names a paper Papers With Code has | |
| not indexed, stderr shows "Not indexed on Papers With Code — available at:" | |
| with public links and metadata before the usual not-found error; cite those | |
| links, not a Papers With Code page. | |
| """ | |
| _WORKFLOW = """ | |
| ## Research workflow | |
| 1. Use `pwc benchmark list --task TASK` to discover active benchmarks, then | |
| `pwc benchmark --name NAME` to inspect a leaderboard. Add | |
| `--max-parameters SIZE` when model size is part of the request. | |
| 2. Use `pwc paper info` to inspect promising results. Add | |
| `--include-resources` when repositories, project pages, or Hugging Face | |
| artifacts matter. | |
| 3. Use exact `pwc paper list --author`, `--task`, `--method`, `--conference`, | |
| `--framework`, and `--organization` filters for known identities or catalog | |
| associations. Combine them to require every association; do not substitute | |
| a keyword search. Add `--search` for title or abstract topic terms. | |
| 4. Use `pwc search` for broader discovery, then `pwc paper read` for primary | |
| evidence. | |
| 5. Expand the literature with `pwc paper related` and use | |
| `pwc paper lineage list` when model or method ancestry matters. | |
| 6. Preserve paper titles, identifiers, and URLs so claims remain traceable. | |
| ## Output and limits | |
| - Interactive output is optimized for people. Benchmark lists remain aligned | |
| when captured; other captured list output uses lossless TSV. Add `--json` for | |
| structured agent or script consumption. | |
| - Stable exit codes are `0` success, `2` invalid usage, `3` network/server | |
| failure, and `4` invalid API response. | |
| - `PWC_API_URL` may select another compatible v1 endpoint. The default is | |
| `https://paperswithcode.co/api/v1`. | |
| - Catalog-filtered paper lists fail closed unless the server confirms every | |
| requested filter; never treat results from an older server as filtered. | |
| - Parameter-filtered benchmark details fail closed unless the server confirms | |
| parameter-filter support and every returned model satisfies the limit. | |
| The research commands contain no authentication, catalog mutation, ingestion, | |
| publication, image, embedding, CRON, or infrastructure-maintenance operations. | |
| """ | |
| class SkillInstallError(Exception): | |
| """An invalid or unsafe skill installation request.""" | |
| def _subcommand_help(action: argparse._SubParsersAction, name: str) -> str: | |
| for choice in action._choices_actions: | |
| if choice.dest == name: | |
| return str(choice.help or "") | |
| return "" | |
| def _command_signature(parser: argparse.ArgumentParser) -> str: | |
| parts: list[str] = [] | |
| for action in parser._actions: | |
| if isinstance(action, argparse._SubParsersAction): | |
| continue | |
| if action.dest == "help": | |
| continue | |
| if not action.option_strings: | |
| parts.append(str(action.metavar or action.dest).upper()) | |
| continue | |
| option = next( | |
| (item for item in action.option_strings if item.startswith("--")), | |
| action.option_strings[0], | |
| ) | |
| if action.nargs == 0: | |
| parts.append(f"[{option}]") | |
| continue | |
| if action.choices: | |
| value = "|".join(str(choice) for choice in action.choices) | |
| else: | |
| value = str(action.metavar or action.dest).upper() | |
| parts.append(f"[{option} {value}]") | |
| return " ".join(parts) | |
| def _command_entries( | |
| parser: argparse.ArgumentParser, prefix: tuple[str, ...] = () | |
| ) -> list[str]: | |
| entries: list[str] = [] | |
| for action in parser._actions: | |
| if not isinstance(action, argparse._SubParsersAction): | |
| continue | |
| for name, child in action.choices.items(): | |
| path = (*prefix, name) | |
| if "handler" in child._defaults: | |
| signature = _command_signature(child) | |
| invocation = " ".join(("pwc", *path, signature)).rstrip() | |
| help_text = _subcommand_help(action, name) | |
| suffix = f" — {help_text.rstrip('.')}" if help_text else "" | |
| entries.append(f"- `{invocation}`{suffix}.") | |
| entries.extend(_command_entries(child, path)) | |
| return entries | |
| def build_skill_md() -> str: | |
| """Build a Skill matching the commands in the installed pwc version.""" | |
| from pwc_cli.cli import build_parser | |
| commands = "\n".join(_command_entries(build_parser())) | |
| return ( | |
| "---\n" | |
| f"name: {SKILL_NAME}\n" | |
| f'description: "{_DESCRIPTION}"\n' | |
| "---\n\n" | |
| f"Generated with `pwc v{__version__}`. Run " | |
| "`pwc skills add --force` to regenerate.\n" | |
| f"{_INTRODUCTION}\n" | |
| "## Commands\n\n" | |
| f"{commands}\n" | |
| f"{_WORKFLOW}\n{_EDIT_WORKFLOW}" | |
| ) | |
| def _remove_existing(path: Path, force: bool) -> None: | |
| if not (path.exists() or path.is_symlink()): | |
| return | |
| if not force: | |
| raise SkillInstallError( | |
| f"skill already exists at {path}; rerun with --force to overwrite" | |
| ) | |
| if path.is_dir() and not path.is_symlink(): | |
| shutil.rmtree(path) | |
| else: | |
| path.unlink() | |
| def _install_to(skills_dir: Path, force: bool) -> Path: | |
| skills_dir = skills_dir.expanduser().resolve() | |
| skills_dir.mkdir(parents=True, exist_ok=True) | |
| target = skills_dir / SKILL_NAME | |
| _remove_existing(target, force) | |
| temporary = Path(tempfile.mkdtemp(prefix=f".{SKILL_NAME}-", dir=skills_dir)) | |
| try: | |
| (temporary / "SKILL.md").write_text(build_skill_md(), encoding="utf-8") | |
| os.replace(temporary, target) | |
| finally: | |
| if temporary.exists(): | |
| shutil.rmtree(temporary) | |
| return target | |
| def _link_to(skills_dir: Path, installed: Path, force: bool) -> Path: | |
| skills_dir = skills_dir.expanduser().resolve() | |
| skills_dir.mkdir(parents=True, exist_ok=True) | |
| link = skills_dir / SKILL_NAME | |
| _remove_existing(link, force) | |
| link.symlink_to(os.path.relpath(installed, skills_dir), target_is_directory=True) | |
| return link | |
| def skills_add(args: argparse.Namespace, _client: object) -> int: | |
| """Install the generated pwc skill in central and optional harness paths.""" | |
| if args.dest is not None and (args.global_ or args.claude): | |
| raise SkillInstallError("--dest cannot be combined with --global or --claude") | |
| if args.dest is not None: | |
| installed = _install_to(args.dest, args.force) | |
| print(f"Installed '{SKILL_NAME}' to {installed}") | |
| return 0 | |
| central_root = CENTRAL_GLOBAL if args.global_ else CENTRAL_LOCAL | |
| installed = _install_to(central_root, args.force) | |
| print(f"Installed '{SKILL_NAME}' to {installed}") | |
| if args.claude: | |
| claude_root = CLAUDE_GLOBAL if args.global_ else CLAUDE_LOCAL | |
| link = _link_to(claude_root, installed, args.force) | |
| print(f"Linked '{SKILL_NAME}' for Claude at {link}") | |
| return 0 | |
| _EDIT_WORKFLOW = """ | |
| ## Editing one paper | |
| Use this workflow only when the user requests edits. Research commands remain anonymous. | |
| 1. Run `pwc auth login --paper PAPER`. Give the user the browser link and code; | |
| they sign in with Hugging Face and authorize that paper for one hour. Use | |
| `--no-browser` on a remote machine. Never extract, print, or copy credentials. | |
| 2. Run `pwc paper edit export PAPER --output edits.json` (the output must not | |
| already exist). It includes paper_id, version, idempotency_key, empty operations, | |
| and current reference data. Change operations, not current. Preserve the | |
| exported version and retry key. Documents may contain at most 50 operations | |
| and 1 MiB of JSON. | |
| 3. Add operations of the form `{"section":"tasks","payload":{"task_ids":[1,2]}}`. | |
| A section operation explicitly replaces that section; preserve unrelated links | |
| and tags. Omitted sections stay unchanged. Allowed sections and payload keys: | |
| tasks/task_ids, methods/method_ids, repositories/repositories, | |
| project_pages/project_pages, hf_artifacts/hf_models+hf_datasets+hf_spaces, | |
| x_threads/x_threads, source_url/source_url (external papers only), and | |
| evaluations. Repository/project-page entries contain url and is_official. | |
| x_threads is a list of x.com or twitter.com post URLs in display order (at | |
| most 10). Link only posts in which the paper's authors or their organization | |
| introduce the paper, never outside accounts; the server captures each post's | |
| preview and rejects deleted or protected posts. | |
| 4. For evaluations, an operation without evaluation_id creates a row. Include | |
| task_id, dataset_id, metrics (a dictionary of existing metric names to scores), | |
| model_name, and the evaluation setup where available. One row can contain | |
| multiple metrics. Add evaluation_id to correct an existing row on this paper; | |
| omitted update fields stay unchanged. Use source_url and methodology to cite | |
| precise evidence when available; source references remain optional. Existing | |
| benchmark/task/metric definitions are required. Do not invent missing IDs or | |
| create benchmarks. Report unsupported results to the user. No evaluation | |
| deletion, paper identity changes, organization edits, or rank overrides. | |
| 5. Run `pwc paper edit preview PAPER --file edits.json`, inspect the before/after | |
| changes, then `pwc paper edit submit PAPER --file edits.json`. Publication is | |
| immediate: no per-batch browser approval. Respect the user's requested scope. | |
| A batch succeeds completely or makes no changes. The response includes status | |
| published and a link to the paper's history. | |
| 6. Retry an uncertain network result using the exact same document and retry key. | |
| A 409 means changed data or a reused key with different edits. Fetch a fresh | |
| export, preserve others' edits, and reconcile. Ask the user if the same score | |
| has conflicting corrections. Once you intentionally revise a previously | |
| submitted batch, use a fresh export/key. A 403 may mean expired authorization, | |
| suspension, or insufficient scope: read the error; do not broaden access. | |
| A 429 indicates the shared account limit: 20 distinct papers per UTC day and | |
| 30 publications per minute. Do not work around account limits. | |
| 7. `pwc auth status --paper PAPER` shows local expiry metadata (revocation is | |
| checked by the server on use). `pwc auth logout --paper PAPER` revokes access. | |
| If authorization expires, keep the prepared file and request browser login | |
| again. Renewing authorization does not require discarding a valid edit document. | |
| Credentials are stored in owner-only files under ~/.config/pwc/edit-credentials, | |
| separately for each API base URL and paper. They never belong in a prompt, edit | |
| file, repository, or command argument. The CLI does not follow edit redirects. | |
| """ | |