Quark Install

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.

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:

  "<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:

  "<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:

  "<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 ===:

  "<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:

  "<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:

"<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.