quark-install

Files (4)

• SKILL.md
• evals.json · evals/
• quark_install_result.schema.json · references/contracts/
• skill-card.md

SKILL.md (first lines)

# Quark Install

## Purpose

Install or verify `amd-quark` without relying on another skill, a Quark checkout, or pre-generated workflow artifacts. Detect the actual hardware, ensure PyTorch matches it, choose the smallest safe Quark install, obtain approval, execute it, and verify the requested capabilities.

## Prerequisites

- GPU support depends on the selected PyTorch build and Quark wheel. Record the actual runtime, host kernel and driver, and GPU architecture (`gfx...` from `gcnArchName` on AMD); verify compatibility with that environment instead of assuming a fixed ROCm version or GPU target.
- No container image is required. If running in a container, record its image name or digest when available and verify GPU device access.
- Inspect and preserve `QUARK_ACCELERATOR`, `PYTORCH_ROCM_ARCH`, `QUARK_BUILD_DISABLE_JIT_FALLBACK`, `HSA_OVERRIDE_GFX_VERSION`, `HIP_VISIBLE_DEVICES`, and `CUDA_VISIBLE_DEVICES`. Include any required changes in the confirmed install plan. Report `PIP_EXTRA_INDEX_URL` only as set or unset because its value may contain credentials.

## Inputs

- Python interpreter or environment to modify. Default to the active interpreter, but make its resolved path explicit.
- Requested Quark source: existing environment, PyPI, an AMD native-wheel index, a local wheel, or a local source directory. Default to the universal PyPI wheel.
- Optional version constraint.
- Compute intent: GPU by default; CPU only after explicit user confirmation.
- Required capabilities: basic Quark import, Quark PyTorch kernels, ONNX custom operators, or `quark-cli`.

Do not require pre-existing environment or install-result artifacts. A user-provided wheel or source directory is an input, not a skill dependency.

## Outputs

Always write `quark_install_result.json` in the user's working directory at a terminal outcome and validate it against [`references/contracts/quark_install_result.schema.json`](references/contracts/quark_install_result.schema.json).

Preserve the compatibility fields `status`, `quark_version`, `install_source`, `extras_installed`, `verification`, and `failure_reason`. Also record the resolved interpreter, imported Quark module path, PyTorch version/backend, GPU availability, whether CPU mode was explicitly confirmed, exact executed commands, and `pip check` result.

- Use `status: "ok"` only when installation and every requested verification pass.
- Use `status: "skipped"` when a suitable existing install is verified or the user declines changes.
- Use `status: "failed"` with the exact failing command and error for install or verification failure.
- Set unrequested optional checks to `null`; do not report `llm_ptq_deps: true` merely because `quark-cli --help` works.

## Installation Rules

- Quark requires Python 3.11, 3.12, or 3.13 and PyTorch 2.2 or newer.
- The `amd-quark` runtime wheel does not install PyTorch. Resolve and verify PyTorch before installing Quark.
- GPU is the default. A CUDA/ROCm build tag alone is insufficient: GPU readiness requires `torch.cuda.is_available()`, a positive device count, and a successful tensor operation on `cuda` (PyTorch uses this device spelling for both CUDA and ROCm).
- If PyTorch is missing, CPU-only, backend-mismatched, or unable to access a GPU, stop and ask whether to install/fix the matching GPU build or explicitly continue in CPU mode. Never install or accept CPU mode silently.
- Install a GPU PyTorch build only from an official index matching detected CUDA/ROCm support. Query available versions first, choose a Python-compatible stable release satisfying `torch>=2.2`, show the exact command, and obtain approval:

  ```bash
  "<PYTHON>" -m pip index versions torch --index-url "https://download.pytorch.org/whl/<GPU_INDEX>"
  "<PYTHON>" -m pip install "torch==<VERSION>" --index-url "https://download.pytorch.org/whl/<GPU_INDEX>"
  ```

- After explicit CPU-mode confirmation, use the official CPU index instead of an unqualified PyPI install:

  ```bash
  "<PYTHON>" -m pip install "torch==<VERSION>" --index-url "https://download.pytorch.org/whl/cpu"
  ```

- The universal PyPI wheel is the safe default. It supports different PyTorch backends but compiles Quark kernels/custom operators on first use and therefore may require a C++ compiler plus `nvcc` or `hipcc`:

  ```bash
  "<PYTHON>" -m pip install "amd-quark"
  ```

- Quark Torch import currently requires Transformers even though the base `amd-quark` wheel may not declare it. When kernel verification is requested and Transformers is absent, preview and confirm a release/model-compatible install; use `"transformers<5.16"` as the current upper bound unless a narrower requirement is known. Treat a missing Transformers module as a dependency failure, not a compiler failure.
- Native-wheel availability changes by release. Never select one from a hard-coded matrix or a bare `--extra-index-url`. Use only an observed candidate whose filename/local version exactly matches the active PyTorch major.minor, CUDA/ROCm major.minor (or CPU), CPython tag, OS, and architecture; pin its complete version with `===`:

  ```bash
  "<PYTHON>" -m pip install "amd-quark===<FULL_VERSION_WITH_VARIANT>" --index-url "<AMD_INDEX_URL>" --extra-index-url "https://pypi.org/simple"
  ```

- Apply the same ABI checks to a user-provided native wheel. A `py3-none-any` wheel is universal. For trusted local input:

  ```bash
  "<PYTHON>" -m pip install "<ABSOLUTE_WHEEL_PATH>"
  "<PYTHON>" -m pip install --no-build-isolation "<ABSOLUTE_SOURCE_DIR>"
  ```

- Use the source form only when the directory contains `pyproject.toml` or `setup.py`, PyTorch is already verified, and the user explicitly trusts and requests executing that source.
- Add `[cli]` only when requested. Before doing so, inspect installed `onnxruntime*` distributions and the dry-run plan because the current CLI extra may add CPU `onnxruntime`; do not silently combine it with `onnxruntime-gpu` or bypass dependencies with `--no-deps`.
- ONNX Runtime variant selection is outside this skill. Verify and report an existing runtime when ONNX custom operators are requested, but do not silently choose or replace its CPU/GPU distribution.
- Always use the same absolute `"<PYTHON>" -m pip`; never use unqualified `pip` or `sudo pip`.

## Interaction Flow

Complete these steps in order.

### Step 1 — Inspect the environment

Resolve `<PYTHON>` to the exact interpreter that would be modified. Quote paths containing spaces. Run read-only checks:

```bash
"<PYTHON>" -c "import platform, sys; print('executable:', sys.executable); print('prefix:', sys.prefix); print('python:', platform.python_version()); print('os:', platform.platform()); print('machine:', platform.machine())"
"<PYTHON>" -m pip --version
"<PYTHON>" -m pip show amd-quark torch
"<PYTHON>" -c "import torch; ok=torch.cuda.is_available(); n=torch.cuda.device_count(); print('torch:', torch.__version__); print('cuda:', torch.version.cuda); print('hip:', torch.version.hip); print('gpu_available:', ok); print('device_count:', n); print('device:', torch.cuda.get_device_name(0) if ok and n else None)"
nvidia-smi --query-gpu=name,driver_version --format=csv,noheader
rocm-smi --showproductname
hipcc --version
```

Run only hardware commands available on the host; command-not-found is evidence, not permission to install utilities. Do not import optional Quark kernels/custom operators during intake because a universal wheel may compile them.

#### Checkpoint 1 — Confirm compute mode

Stop before Quark planning if Python is unsupported, PyTorch is below 2.2, hardware is ambiguous, PyTorch is CPU-only, the build family conflicts with detected hardware, or a GPU build cannot access a device.

Ask: “I found `<EVIDENCE>`. Shall I install/fix the matching GPU PyTorch build, or do you explicitly want CPU mode?”

Do not continue in CPU mode without an explicit answer. If GPU mode is selected, show and approve the exact official-index PyTorch command, then verify a real GPU tensor operation before continuing.

### Step 2 — Select the install

1. If a suitable Quark version is already installed and no upgrade or reinstall was requested, skip installation and proceed to verification.
2. Prefer an explicitly requested and validated local wheel/source.
3. Use a native wheel only after exact candidate and ABI validation; otherwise use the universal PyPI wheel.
4. Add a requested version constraint to the package spec, for example `"amd-quark==<VERSION>"` or `"amd-quark[cli]==<VERSION>"`.
5. Preview every required package change, including Transformers for kernel use, with `"<PYTHON>" -m pip install --dry-run "<PACKAGE_SPEC>"`. If dry-run is unsupported, report that limitation rather than mutating the environment.
6. Treat the installed distribution metadata as authoritative. Do not claim the source-tree version or dependency limits apply to a different published release.

### Step 3 — Confirm changes

Show:

- the resolved interpreter and environment;

From amd/Quark, MIT.

More from amd/Quark