docs: align CLAUDE.md's AITER install with the README pin - #290
Conversation
CLAUDE.md told you to build AITER from source master and said nothing about a version. The README says the opposite -- "Pin `0.1.10`: it is the version this repo is built and tested against" -- and `prefill_rocm.py` records the same value as `_AITER_LAST_VALIDATED`. Following CLAUDE.md therefore left you on a build many releases ahead of the pin, with a different C ABI: symbols the shim expects are renamed, hidden rather than `extern "C"`, or absent outright. That has already cost one C++ shim design, which was drafted against a source checkout and turned out to be unbuildable on the installed wheel. The wheel command is copied verbatim from the README so the two cannot drift on whitespace, and links to the section that explains why it is `--extra-index-url` rather than `--index-url`. The source build is documented rather than removed -- it is legitimate, just untested here -- and the read-the-installed-tree rule is spelled out with the two commands that settle it, since that is the specific trap. Also adds MI350X to the arch/codename line. gfx950 covers both MI350X and MI355X, and the README already says so as of #288; the evidence strings in the capability table were measured on an MI350X, so the narrower list read as a contradiction. Docs only: no Python touched, so there are no tests to run beyond pre-commit.
There was a problem hiding this comment.
Pull request overview
Updates contributor documentation to align AITER installation guidance in CLAUDE.md with the repository’s validated/pinned AITER version and the README, reducing the risk of contributors building against an untested (and ABI-incompatible) AITER source checkout.
Changes:
- Switches
CLAUDE.mdAITER install instructions to lead with the pinnedamd-aiter==0.1.10wheel install command (matchingREADME.md). - Reframes the AITER source build path as valid but explicitly untested, and adds guidance to inspect the installed AITER artifacts when working on the C++ shim.
- Expands the gfx950 SKU mapping to include MI350X alongside MI355X.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The install command this file now recommends was copied from the README, but neither document says which interpreters it can actually satisfy. The rocm-7.1.1 channel carries exactly two wheels -- amd_aiter-0.1.10-cp310 and -cp312 -- so on 3.11, 3.13 or 3.14 the command fails with "No matching distribution found", and there is no pinned-version fallback: public PyPI tops out at a stale 0.1.7.post2.dev18 and the nightlies index only carries >= 0.1.16. Verified by resolving it rather than by reading the index listing: `pip download --no-deps amd-aiter==0.1.10 --extra-index-url https://pypi.amd.com/rocm-7.1.1/simple` pulls amd_aiter-0.1.10-cp312-cp312-linux_x86_64.whl (264 MB) on CPython 3.12.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
CLAUDE.md:114
- The inline code span for the source-build command is split across two lines. GitHub/CommonMark code spans are single-line, so this can render incorrectly and make the command harder to copy/paste.
A source build (`git clone --recursive https://github.com/ROCm/aiter.git &&
cd aiter && python3 setup.py develop`) tracks master, which is **many releases
ahead of the pin with a different C ABI** — symbols the shim expects are
renamed, hidden rather than `extern "C"`, or absent. Nothing stops you running
one, but treat it as untested here.
|
Suppressed comment in review 4984634686 — declined, no change.
|
Summary
CLAUDE.mdtold contributors to build AITER from source master and said nothing about a version.README.mdsays the opposite — "Pin0.1.10: it is the version this repo is built and tested against" — andprefill_rocm.pyrecords the same value as_AITER_LAST_VALIDATED. Following the project instructions therefore put you on an untested build.What changed
CLAUDE.md— the AITER install block now leads with the pinned wheel, copied verbatim from the README; documents the source build as legitimate-but-untested rather than deleting it; and spells out the read-the-installed-tree rule for shim work. Also adds MI350X to the arch/codename line.Why it matters
Master is many releases ahead of the pin with a different C ABI — symbols the shim expects are renamed, hidden rather than
extern "C", or absent outright. Concretely, between the installedamd-aiter 0.1.10and a recent source checkout:mla_reduce_v1does not exist at all, the MLA asm entry points aretorch::Tensor&and C++-mangled rather thanaiter_tensor_t*andextern "C", andreshape_and_cache_flashchanges signature.This is not hypothetical. A C++ shim design was drafted against a source checkout and turned out to be unbuildable on the installed wheel — caught only when
nm -Don the installed.sodisagreed with the checkout's header. That is why the twonm -D/ header commands are now in the file: they are what settles the question in seconds.The wheel command is copied byte-for-byte from the README so the two cannot drift, and links to the section explaining why it must be
--extra-index-urlrather than--index-url(AITER's own dependencies still need to resolve from PyPI).MI350X
gfx950 covers both MI350X and MI355X.
README.mdalready says so as of #288, and theevidencestrings in the capability table were measured on an MI350X — so the narrowerMI355X = gfx950line read as a contradiction against the repo's own recorded measurements.Test plan
Docs only — no Python touched, so there are no tests to run.
pre-commit run --files CLAUDE.md— clean (markdownlint included).### Install AITER wheel packageexists atREADME.md:428.pip installline is byte-identical toREADME.md:435.