wafer-cli 0.2.19__tar.gz

wafer_cli-0.2.19/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: wafer-cli
+Version: 0.2.19
+Summary: CLI tool for running commands on remote GPUs and GPU kernel optimization agent
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12.0
+Requires-Dist: trio>=0.24.0
+Requires-Dist: trio-asyncio>=0.15.0
+Requires-Dist: wafer-core>=0.1.0
+Requires-Dist: perfetto>=0.16.0
+Requires-Dist: posthog>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: diff-cover>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"

wafer_cli-0.2.19/README.md

@@ -0,0 +1,242 @@
+# Wafer CLI
+
+Run GPU workloads, optimize kernels, and query GPU documentation.
+
+## Getting Started
+
+```bash
+# Install
+cd apps/wafer-cli && uv sync
+
+# Use staging (workspaces and other features require staging)
+wafer config set api.environment staging
+
+# Login
+wafer login
+
+# Run a command on a remote GPU
+wafer remote-run -- nvidia-smi
+```
+
+## Commands
+
+### `wafer login` / `wafer logout` / `wafer whoami`
+
+Authenticate with GitHub OAuth.
+
+```bash
+wafer login          # Opens browser for GitHub OAuth
+wafer whoami         # Show current user
+wafer logout         # Remove credentials
+```
+
+### `wafer remote-run`
+
+Run any command on a remote GPU.
+
+```bash
+wafer remote-run -- nvidia-smi
+wafer remote-run --upload-dir ./my_code -- python3 train.py
+```
+
+### `wafer workspaces`
+
+Create and manage persistent GPU environments.
+
+**Available GPUs:**
+
+- `MI300X` - AMD Instinct MI300X (192GB HBM3, ROCm)
+- `B200` - NVIDIA Blackwell B200 (180GB HBM3e, CUDA) - default
+
+```bash
+wafer workspaces list
+wafer workspaces create my-workspace --gpu B200 --wait   # NVIDIA B200
+wafer workspaces create amd-dev --gpu MI300X             # AMD MI300X
+wafer workspaces ssh <workspace-id>
+wafer workspaces delete <workspace-id>
+```
+
+### `wafer agent`
+
+AI assistant for GPU kernel development. Helps with CUDA/Triton optimization, documentation queries, and performance analysis.
+
+```bash
+wafer agent "What is TMEM in CuTeDSL?"
+wafer agent -s "optimize this kernel" < kernel.py
+```
+
+### `wafer evaluate`
+
+Evaluate kernel correctness and performance against a reference implementation.
+
+**Functional format** (default):
+```bash
+# Generate template files
+wafer evaluate make-template ./my-kernel
+
+# Run evaluation
+wafer evaluate --impl kernel.py --reference ref.py --test-cases tests.json --benchmark
+```
+
+The implementation must define `custom_kernel(inputs)`, the reference must define `ref_kernel(inputs)` and `generate_input(**params)`.
+
+**KernelBench format** (ModelNew class):
+```bash
+# Extract a KernelBench problem as template
+wafer evaluate kernelbench make-template level1/1
+
+# Run evaluation
+wafer evaluate kernelbench --impl my_kernel.py --reference problem.py --benchmark
+```
+
+The implementation must define `class ModelNew(nn.Module)`, the reference must define `class Model`, `get_inputs()`, and `get_init_inputs()`.
+
+### `wafer wevin -t ask-docs`
+
+Query GPU documentation using the docs template.
+
+```bash
+wafer wevin -t ask-docs --json -s "What causes bank conflicts in shared memory?"
+```
+
+### `wafer corpus`
+
+Download documentation to local filesystem for agents to search.
+
+```bash
+wafer corpus list
+wafer corpus download cuda-programming-guide
+```
+
+---
+
+## Customization
+
+### `wafer remote-run` options
+
+```bash
+wafer remote-run --image pytorch/pytorch:2.5.1-cuda12.4-cudnn9-devel -- python3 script.py
+wafer remote-run --require-hwc -- ncu --set full python3 bench.py   # Hardware counters for NCU
+```
+
+### `wafer evaluate` options
+
+```bash
+wafer evaluate --impl k.py --reference r.py --test-cases t.json \
+    --target vultr-b200 \    # Specific GPU target
+    --benchmark \            # Measure performance
+    --profile                # Enable torch.profiler + NCU
+```
+
+### `wafer push` for multi-command workflows
+
+```bash
+WORKSPACE=$(wafer push ./project)
+wafer remote-run --workspace-id $WORKSPACE -- python3 test1.py
+wafer remote-run --workspace-id $WORKSPACE -- python3 test2.py
+```
+
+### Profile analysis
+
+```bash
+wafer nvidia ncu analyze profile.ncu-rep
+wafer nvidia nsys analyze profile.nsys-rep
+```
+
+---
+
+## Advanced
+
+### Local targets
+
+Bypass the API and SSH directly to your own GPUs:
+
+```bash
+wafer targets list
+wafer targets add ./my-gpu.toml
+wafer targets default my-gpu
+```
+
+### Defensive evaluation
+
+Detect evaluation hacking (stream injection, lazy evaluation, etc.):
+
+```bash
+wafer evaluate --impl k.py --reference r.py --test-cases t.json --benchmark --defensive
+```
+
+### Other tools
+
+```bash
+wafer perfetto <trace.json> --query "SELECT * FROM slice"   # Perfetto SQL queries
+wafer capture ./script.py                                    # Capture execution snapshot
+wafer compiler-analyze kernel.ptx                            # Analyze PTX/SASS
+```
+
+### ROCm profiling (AMD GPUs)
+
+```bash
+wafer rocprof-sdk ...
+wafer rocprof-systems ...
+wafer rocprof-compute ...
+```
+
+---
+
+## Shell Completion
+
+Enable tab completion for commands, options, and target names:
+
+```bash
+# Install completion (zsh/bash/fish)
+wafer --install-completion
+
+# Then restart your terminal, or source your shell config:
+source ~/.zshrc  # or ~/.bashrc
+```
+
+Now you can tab-complete:
+- Commands: `wafer eva<TAB>` → `wafer evaluate`
+- Options: `wafer evaluate --<TAB>`
+- Target names: `wafer evaluate --target v<TAB>` → `wafer evaluate --target vultr-b200`
+- File paths: `wafer evaluate --impl ./<TAB>`
+
+---
+
+## AI Assistant Skills
+
+Install the Wafer CLI skill to make wafer commands discoverable by your AI coding assistant:
+
+```bash
+# Install for all supported tools (Claude Code, Codex CLI, Cursor)
+wafer skill install
+
+# Install for a specific tool
+wafer skill install -t cursor    # Cursor
+wafer skill install -t claude    # Claude Code
+wafer skill install -t codex     # Codex CLI
+
+# Check installation status
+wafer skill status
+
+# Uninstall
+wafer skill uninstall
+```
+
+### Installing from GitHub (Cursor)
+
+You can also install the skill directly from GitHub in Cursor:
+
+1. Open Cursor Settings (Cmd+Shift+J / Ctrl+Shift+J)
+2. Navigate to **Rules** → **Add Rule** → **Remote Rule (Github)**
+3. Enter: `https://github.com/wafer-ai/skills`
+4. Cursor will automatically discover skills in `.cursor/skills/`
+
+The skill provides comprehensive guidance for GPU kernel development, including documentation lookup, trace analysis, kernel evaluation, and optimization workflows.
+
+---
+
+## Requirements
+
+- Python 3.10+
+- GitHub account (for authentication)

wafer_cli-0.2.19/pyproject.toml

@@ -0,0 +1,120 @@
+[project]
+name = "wafer-cli"
+version = "0.2.19"
+description = "CLI tool for running commands on remote GPUs and GPU kernel optimization agent"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.12.0",
+    "trio>=0.24.0",
+    "trio-asyncio>=0.15.0", # Bridge asyncssh (asyncio) to trio for async SSH
+    # Wafer core for environments and utils (includes rollouts)
+    "wafer-core>=0.1.0",
+    "perfetto>=0.16.0",
+    "posthog>=3.0.0",  # Analytics tracking
+]
+
+[project.scripts]
+wafer = "wafer.cli:main"
+
+[tool.uv.sources]
+wafer-core = { workspace = true }
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "diff-cover>=8.0.0",
+    "ruff>=0.4.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["wafer*"]
+
+[tool.setuptools.package-data]
+wafer = ["GUIDE.md", "skills/*/SKILL.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+preview = true  # Required for PLR1702 (too-many-nested-blocks)
+
+[tool.ruff.lint]
+select = [
+    "E",       # pycodestyle errors
+    "F",       # pyflakes
+    "I",       # isort (import sorting)
+    "ANN",     # flake8-annotations (enforce type annotations)
+    "ASYNC",   # flake8-async (trio/asyncio best practices)
+    "B",       # flake8-bugbear (common bugs)
+    "UP",      # pyupgrade (modern Python patterns)
+    "PLR0913", # too-many-arguments (Tiger Style: "hourglass shape: few parameters")
+    "PLR0915", # too-many-statements (Tiger Style: 70 line limit)
+    "PLR1702", # too-many-nested-blocks (Tiger Style: "centralize control flow")
+    "PLW2901", # redefined-loop-variable (Carmack SSA: single assignment)
+    "RET506",  # superfluous-else-raise (explicit control flow)
+    "RET507",  # superfluous-else-continue (explicit control flow)
+    "A",       # flake8-builtins (shadowing builtins like list, str)
+    "RUF018",  # assignment-in-assert (catches typos)
+    "TRY002",  # raise-vanilla-exception (use specific exceptions)
+    "TRY003",  # raise-vanilla-args (proper exception messages)
+    "TRY004",  # type-check-without-type-error (use TypeError for type checks)
+    "TRY201",  # verbose-raise (use bare raise)
+    "TRY300",  # try-consider-else (clear control flow)
+    "TRY400",  # error-instead-of-exception (use logging.exception)
+]
+ignore = [
+    "E501",    # Line too long (handled by formatter)
+    "B008",    # Typer uses function calls in defaults
+    "TRY003",  # Avoid specifying long messages outside exception class (too opinionated - revisit later)
+    "TRY300",  # Consider moving to else block (too opinionated about try/except style - revisit later)
+    "TRY400",  # Use logging.exception instead of logging.error (we prefer explicit error logging - revisit later)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ANN001", "ANN201", "ANN202", "ANN204"]  # Don't require type annotations in tests
+"wafer/evaluate.py" = ["PLR0915", "PLR1702", "E402", "PLW2901", "ASYNC221"]  # complex deployment flows - TODO: refactor
+"wafer/output.py" = ["ANN401"]  # Output collector uses **kwargs for flexible event data
+"wafer/autotuner.py" = ["PLR0915", "PLR1702", "B007", "B904"]  # complex sweep logic - TODO: refactor
+"wafer/ncu_analyze.py" = ["PLR0915", "PLR1702"]  # complex parsing logic - TODO: refactor
+"wafer/cli.py" = ["PLR0915"]  # CLI commands can be long - TODO: refactor
+"wafer/targets.py" = ["PLR1702"]  # complex target init flow - TODO: refactor
+"wafer/workspaces.py" = ["PLR1702"]  # SSE streaming has nested blocks - TODO: refactor
+"wafer/kernel_scope.py" = ["ANN001", "ANN202", "PLR0913"]  # complex filtering logic
+"wafer/api_client.py" = ["PLR0913"]  # API client needs many params
+"wafer/rocprof_compute.py" = ["PLR0913", "B904"]  # profiler commands need many params
+"wafer/rocprof_sdk.py" = ["PLR0913"]  # profiler commands need many params
+"wafer/rocprof_systems.py" = ["PLR0913"]  # profiler commands need many params
+
+[tool.ruff.lint.pylint]
+max-args = 7             # Max function arguments (Tiger Style: few parameters)
+max-statements = 70      # Max statements per function (Tiger Style: 70 line limit)
+max-branches = 12        # Max if/elif branches
+max-nested-blocks = 5    # Max nesting depth (Linus rule: "if you need more than 3 levels, you're screwed")
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--cov=wafer",
+    "--cov-report=term-missing",
+    "--cov-report=xml:coverage.xml",
+    "--cov-report=html:coverage/html",
+]
+
+[tool.coverage.run]
+source = ["wafer"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+    "raise NotImplementedError",
+]

wafer_cli-0.2.19/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+