[danielmawhirter]

Design discussion: ARM64 documentation follow-up, confirmed Python range.

Summary

Make the DGX Spark guide wheel-first for Python 3.11–3.14, with optional CPU or GPU Faiss for link prediction and a link to the engine's connector/text extras. Keep CUDA tooling and a source checkout specific to the optional GPU Faiss build.

Document prebuilt Linux x86_64/ARM64 and macOS Apple silicon wheels as available for this release. Preserve WSL2-only Windows support. Documentation only; no packaging, runtime or publication changes.

Change map

Maintained file-by-file change map

Testing Done

Passed: repository documentation checker (259 files), 36 documentation unit tests, catalog documentation check, and git diff --check. Shell examples are unchanged from the prior successful bash -n verification. Reviewed commands and version claims against package metadata, build scripts and public wheel indexes. Flake8/isort are not applicable: no Python files changed.

Installation examples and DGX Spark GPU/Faiss workloads were not executed. The existing CPU wheel qualification covers Python 3.11–3.14; this docs-only follow-up adds no runtime validation.

Hotfix Context

Release documentation follow-up to merged #92; ships with the release publishing macOS and ARM64 wheels and assumes those wheels are available.

Checklist

• Breaking changes listed: none.
• Installation examples and documentation updated.
• Documentation and reference checks completed; no runtime changes require new tests.

[danielmawhirter]

Change map

File	Function / scope	What changed	Why
packages/kumo-engine/README.md	Installation guidance	State prebuilt wheel availability for Linux x86_64/ARM64 and macOS Apple silicon, and link the optional ARM64 GPU Faiss instructions.	Replace the obsolete ARM64 source-only route with installation guidance for the release publishing these wheels.
packages/kumo-engine/dgx-spark.md	DGX Spark installation	Lead with Python 3.11–3.14 engine-wheel installation and extras; separate optional CPU/CUDA retrieval and GPU Faiss build requirements.	Make installation wheel-first while keeping Faiss, training-device selection and Python/CUDA dependency availability distinct.

Requirement: this documentation ships with the release publishing macOS and ARM64 wheels and assumes those wheels are available. The existing Spark guide requires engine source builds and presents GPU Faiss as mandatory. This is the smallest documentation-only follow-up. Verification: documentation checker (259 files), 36 documentation unit tests, catalog documentation check and diff whitespace checks passed; shell examples are unchanged from the prior successful syntax checks. Commands and dependency versions were reviewed against primary sources. Installation and GPU workloads were not executed. Stop after these two guides are accurate; no packaging changes, publication or additional GPU validation is included.

[coderabbitai]

Walkthrough

The README now lists Linux ARM64 as a wheel target and links to the DGX Spark guide. The guide documents prebuilt ARM64 wheel requirements and installation, CPU Faiss setup for link prediction, and optional CUDA-enabled PyTorch and GPU Faiss setup. The GPU Faiss instructions no longer include rebuilding Kumo Engine or installing Rust.

Merge Risk: Low · up to 2799a

The docs may send ARM64 and Apple silicon users to wheel installs that are not yet on PyPI, and the guide no longer gives a source-build fallback. Merge this alongside the wheel release, or restore the fallback guidance, to avoid confusing installs.

Architecture risk: Low · up to 2799a

The change affects 1 system.

Changed systems: packages/kumo-engine

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — packages/kumo-engine (library) was modified; 2 changed files map to changed impact.

Before / after behavior

• observed — Modified behavior in packages/kumo-engine/README.md: The GPU Faiss guidance now links to the DGX Spark guide’s optional CUDA link-prediction build section; the previous text only said to build from source on ARM64. The CPU-extra platform-backend statement remains.
• observed — Modified behavior in packages/kumo-engine/README.md: The wheel description now includes Linux ARM64 alongside Linux x86_64 and macOS on Apple silicon. The previous text identified the PyPI wheel targets and directed ARM64 users to the DGX Spark guide; the replacement describes ARM64 installation and optional GPU Faiss setup as covered by that guide.
• observed — Modified behavior in packages/kumo-engine/dgx-spark.md: Replaces source-build guidance with prebuilt ARM64 wheel requirements, qualification scope, installation steps, and directions to quickstart and extras documentation. The base install does not require Faiss; link-prediction retrieval does.
• observed — Modified behavior in packages/kumo-engine/dgx-spark.md: Adds CPU Faiss installation and specifies that it does not select the PyTorch build or training device. Link prediction using CPU Faiss requires selecting CPU execution, including when a GPU is available; model reload likewise uses the CPU accelerator. The instructions also specify choosing one Faiss backend per environment.

Pre-merge checks: 2 · 1

Failed checks: 1 inconclusive

Check name	Status	Explanation	Resolution
Change Map Design Review		The marked change-map comment is not available, so its design rationale, scope descriptions, verification, and stopping condition cannot be assessed. The diff adds a wheel-availability claim, while th…	Provide the full marked comment and linked design discussion. Provide wheel publication and documentation rollout evidence to assess the availability claim.

Passed checks: 2 passed

Check name	Status	Explanation
Pr Size		The pull request changes 2 files. The limit is 40 files.
Public Resource Access		The added PyTorch page and GitHub guide are publicly accessible. The new GitHub fragment matches a heading in the PR. That heading will be available on main after the PR merges.

Full details: Change Map Design Review

Explanation

The marked change-map comment is not available, so its design rationale, scope descriptions, verification, and stopping condition cannot be assessed. The diff adds a wheel-availability claim, while the release workflow defines ARM64 and Apple silicon build targets; neither establishes when those wheels are published. The reported publication-timing concern remains unverified.

Resolution

Provide the full marked comment and linked design discussion. Provide wheel publication and documentation rollout evidence to assess the availability claim.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[coderabbitai]

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

Other comments: 1

packages/kumo-engine/dgx-spark.md: 1

5-6: Minor · Functional Correctness · Quick win

Pin the engine installation to the release checked by the reader.

The guide checks a release-specific ARM64 wheel, but both engine installs are unpinned. pip can therefore install a newer compatible release than the one the reader checked. Pin the two package requirements to the selected release and use a matching release-specific PyPI link. Do not change the Faiss builder checkout: scripts/build_faiss_gpu_arm64_wheel.sh builds Faiss independently of the Kumo Engine release.

Suggested engine version pinning

+# Set this to the release checked above.
+KUMO_VERSION="<release>"
+
-python -m pip install --only-binary=kumo-engine kumo-engine
+python -m pip install --only-binary=kumo-engine \
+  "kumo-engine==${KUMO_VERSION}"
...
-python -m pip install 'kumo-engine[cpu]'
+python -m pip install "kumo-engine[cpu]==${KUMO_VERSION}"

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/kumo-engine
• Branch: dm-arm64-install-docs
• File: .coderabbit.yaml
• Commit: d39f901
• Layers: Repository YAML
• Review profile: QUIET
• Plan: Enterprise
• Run ID: b4f9af1e-bcb1-44fd-acee-87df63b1396a

Commits

Reviewing files that changed from the base of the PR and between 6aafd69 and d39f901.

Files selected for processing: 2

• packages/kumo-engine/README.md
• packages/kumo-engine/dgx-spark.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

[coderabbitai]

Actionable comments posted: 1

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

Other comments: 1

packages/kumo-engine/dgx-spark.md: 1

4-4: Minor · Functional Correctness · Quick win

Restore the ARM64 source-build fallback.

If the selected release or package index lacks a matching wheel, the wheel-only command fails. The root README directs users to this guide for an ARM64 source build, but the guide no longer provides one. Restore the source-build instructions or link to the local-build and ARM64 instructions.

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/kumo-engine
• Branch: dm-arm64-install-docs
• File: .coderabbit.yaml
• Commit: 2799a88
• Layers: Repository YAML
• Review profile: QUIET
• Plan: Enterprise
• Run ID: a8c8e916-a4d4-411c-9077-e61dc88d8340

Commits

Reviewing files that changed from the base of the PR and between ad23f41 and 2799a88.

Files selected for processing: 2

• packages/kumo-engine/README.md
• packages/kumo-engine/dgx-spark.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

[Victsm]

The wheel-first instructions otherwise look good. The new availability wording is premature: as of 2026-11-06 20:09 UTC, PyPI lists only manylinux_2_34_x86_64 wheels for 1.0.0 and 1.0.1, with no ARM64 or macOS wheels. Please retain the prior conditional availability/source-build fallback until those artifacts are published, or explicitly present these as instructions for the upcoming release. This confirms the current bot finding; no runtime-code change is needed.

[danielmawhirter]

@Victsm There's a tradeoff here. If we merge this PR saying "wheels are available" before release on pypi, then GitHub will say "wheels are available" before it's true. If we do not say "wheels are available", then the README which is published on PyPi will have the conditional language even after release.

I prefer the version where github is briefly ahead of reality, then the release catches up

[Victsm]

Re-reviewed 2799a88. No source blocker. Daniel's release-packaging explanation is reasonable: the packaged README should describe the release it ships with. Approving on that basis; coordinate publication of the ARM64/macOS wheels with this release (PyPI currently still has only x86_64 wheels). Documentation checks and all five Bash examples pass; no ARM64/GPU installation was run.