docs: add NIXL documentation (Fern platform) #1946
Open
lluki wants to merge 9 commits into
Open
Conversation
Comprehensive documentation for the NVIDIA Inference Xfer Library (NIXL): - Getting Started: Overview, Architecture (with D2 sequence diagrams), Quick Start, Contribution Guide - User Guide: 12 backend pages, ETCD metadata exchange, Telemetry - Developer Guide: Building from Source (Docker/C++/Python/Rust), Backend Plugin development - Examples: Basic Transfer, GDS, Remote Storage, NIXL-EP, ETCD, Telemetry - API Reference: C++, Python, Rust, Device, Southbound Plugin - Resources: Environment Variables, Troubleshooting - Fern platform config with NVIDIA branding, interactive stack diagram, per-phase data flow diagrams, custom CSS, and footer component
Add 6 benchmarking documentation pages (968 lines) under User Guide: - NIXLBench: overview, build (Docker + native), usage guide with 4 communication patterns, CLI reference, and troubleshooting - KVBench: overview, build (Docker + venv), command reference for all 5 subcommands, model config YAML schemas, and DeepSeek R1 / Llama 3.1 end-to-end examples All pages terminology-normalized, cross-linked to backend User Guide pages, and fern check clean.
Update the Fern CLI pin for current local preview support and render diagram hover emphasis with a non-layout-changing box shadow to prevent flex-row oscillation.
|
👋 Hi lluki! Thank you for contributing to ai-dynamo/nixl. Your PR reviewers will review your contribution then trigger the CI to test your changes. 🚀 |
Contributor
📝 WalkthroughWalkthroughThis change adds the NIXL Fern documentation site, API and backend references, user guides, runnable examples, transfer diagrams, benchmark documentation, generated stack metadata, navigation, styling, and planning records for documentation milestones v1.0 and v1.1. ChangesNIXL documentation rollout
Estimated code review effort: 5 (Critical) | ~120 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 127
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/diagrams/remote-storage/nixl_remote_storage_03_write_dark.d2 (1)
1-69: 🩺 Stability & Availability | 🔴 Critical | ⚡ Quick winCI failure: missing SPDX copyright header.
Pipeline reports the SPDX header check failing for this file. Shares the same root cause as the identical failure on
docs/diagrams/etcd-metadata/nixl_etcd_metadata_03_fetch_light.d2— see consolidated comment.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/diagrams/remote-storage/nixl_remote_storage_03_write_dark.d2` around lines 1 - 69, Add the repository-required SPDX copyright and license header to the top of the diagram file, before the existing sequence-diagram content. Match the exact header format and attribution used by adjacent D2 documentation files, without changing the diagram definition.Source: Pipeline failures
docs/diagrams/etcd-metadata/nixl_etcd_metadata_03_fetch_light.d2 (1)
1-59: 🩺 Stability & Availability | 🔴 Critical | ⚡ Quick winCI failure: missing SPDX copyright header.
Same pipeline failure as
docs/diagrams/remote-storage/nixl_remote_storage_03_write_dark.d2— see consolidated comment for the shared fix.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/diagrams/etcd-metadata/nixl_etcd_metadata_03_fetch_light.d2` around lines 1 - 59, Add the repository-standard SPDX copyright header to the top of the diagram, matching the header format used by docs/diagrams/remote-storage/nixl_remote_storage_03_write_dark.d2. Preserve the existing sequence_diagram content unchanged.Source: Pipeline failures
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.planning/MILESTONES.md:
- Line 26: Update the backend count in the User Guide milestone entry to 12,
matching docs/index.yml and docs/getting-started/architecture.md; only document
an additional backend instead if one is actually intended and added explicitly.
In @.planning/milestones/v1.1-MILESTONE-AUDIT.md:
- Line 129: Reconcile the backend discrepancy between the NIXLBench overview and
the --backend CLI audit note by using the same backend source set and count in
both. Update the audit entry to reflect the overview’s 4 network plus 7 storage
backends, including whether UCCL-P2P is present, or revise the overview to match
the documented CLI values.
In @.planning/milestones/v1.1-REQUIREMENTS.md:
- Around line 3-4: Reconcile the milestone metadata in v1.1-REQUIREMENTS.md:
either update the traceability table entries in the requirements section to
reflect completed delivery, or change the top-level Archived/Status metadata
from SHIPPED to match the remaining Pending requirements. Ensure the final
metadata and requirement states consistently describe the milestone.
In @.planning/phases/32-navigation-and-directory-setup/32-01-PLAN.md:
- Around line 40-42: Update the execution_context block in the plan to replace
the workstation-specific absolute references with repository-relative paths or
documented tool aliases, while preserving the existing workflow and summary
template references.
- Around line 91-102: The verification for the Benchmarking navigation in the
plan must validate structure rather than only substring counts. Update the
<verify> command to assert each required section/path exactly once, parse
docs/index.yml with the repository’s available YAML/Fern tooling, and check
nesting, ordering, collapsed settings, and that the Benchmarking parent lacks a
path attribute.
In @.planning/phases/32-navigation-and-directory-setup/32-02-PLAN.md:
- Around line 7-11: Update the benchmark documentation paths throughout plan
phases 32 and 35–43 from docs/development/benchmarking/... to the actual
docs/user-guide/benchmarking/... tree. Adjust the related verification commands,
navigation-key references, and acceptance criteria consistently so they target
the existing pages and do not create duplicate stubs.
- Around line 53-55: Update the execution_context entries in the plan to remove
the machine-specific /home/omrik/Projects/nixl.gitlab prefix, using
repository-relative paths or the documented workflow location that resolves
consistently for all checkouts.
In @.planning/phases/32-navigation-and-directory-setup/32-02-SUMMARY.md:
- Around line 9-12: Update the benchmarking file paths listed in the summary and
the “all paths resolve” claim to use the current docs/user-guide/benchmarking
directory, including all references covered by the additional affected lines. If
documenting the move instead, clearly record the old-to-new directory transition
so future path audits remain accurate.
In @.planning/phases/32-navigation-and-directory-setup/32-RESEARCH.md:
- Around line 47-62: Use docs/user-guide/benchmarking/ as the canonical
directory throughout the planning artifacts. In
.planning/phases/32-navigation-and-directory-setup/32-RESEARCH.md, revise the
directory discrepancy resolution and stub-file paths; update
.planning/phases/35-kvbench-overview-and-build/35-RESEARCH.md paths and
navigation examples; and update
.planning/phases/35-kvbench-overview-and-build/35-01-PLAN.md files_modified and
all downstream references consistently.
In @.planning/phases/32-navigation-and-directory-setup/32-VALIDATION.md:
- Around line 1-7: Synchronize the sign-off metadata in the phase validation
document with the passed result recorded by 32-VERIFICATION.md: update status,
nyquist_compliant, wave_0_complete, and approval to their validated values, or
instead mark the companion verification as pending so both documents agree.
In @.planning/phases/32-navigation-and-directory-setup/32-VERIFICATION.md:
- Around line 39-40: Update the NIXLBench and KVBench paths in
.planning/phases/32-navigation-and-directory-setup/32-VERIFICATION.md lines
39-40 to use docs/user-guide/benchmarking/... instead of
docs/development/benchmarking/.... Update the corresponding directory and file
existence checks in
.planning/phases/32-navigation-and-directory-setup/32-VALIDATION.md lines 44-48
to use the same actual benchmark paths.
- Around line 2-6: Synchronize Phase 32 metadata with Fern’s actual CI result:
in .planning/phases/32-navigation-and-directory-setup/32-VERIFICATION.md lines
2-6, record the result before marking the phase fully passed; in
32-VALIDATION.md lines 1-7, update status, nyquist_compliant, and
wave_0_complete accordingly; and in lines 69-78, complete the validation
sign-off or explicitly keep the phase pending.
In @.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md:
- Around line 7-10: Use docs/user-guide/benchmarking/nixlbench as the canonical
NIXLBench path throughout the planning documentation. In
.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md lines 7-10,
update modified-file and navigation paths; in
.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md lines 107-124,
replace the development/benchmarking navigation example; and in
.planning/research/PITFALLS.md lines 135-145, update the recommended navigation
template.
- Around line 194-205: Align the post-install environment setup with the
documented installation prefix: update the PATH and LD_LIBRARY_PATH exports to
use the prefix configured by the setup command, or explicitly configure that
command with prefix=/usr/local/nixlbench. Keep the nixl_path option and
resulting installation locations consistent.
In @.planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md:
- Around line 22-23: Add a blank line immediately after each affected Markdown
heading at lines 22, 25, 33, and 41 in the summary document, preserving all
existing content and navigation details.
- Around line 7-8: Planning evidence references outdated documentation and
artifact paths. In
.planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md lines 7-8,
replace the Nixlbench paths with docs/user-guide/benchmarking/nixlbench/index.md
and build.md; in
.planning/phases/35-kvbench-overview-and-build/35-VERIFICATION.md lines 28-29,
update navigation evidence to docs/user-guide/benchmarking/kvbench/build.md; in
the same file lines 37-46, correct the KVBench artifact and link-verification
paths and rerun the verification report.
In @.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md:
- Around line 95-97: Correct the duplicated directory in the planned overview
links: update the entries at
.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md lines 95-97 and
.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md lines 95-97 to
use the sibling-relative links ./build and ./usage.
In @.planning/phases/33-nixlbench-overview-and-build/33-VALIDATION.md:
- Around line 41-44: Update the verification commands in the validation table
entries 33-01-01 through 33-01-04 to target
docs/user-guide/benchmarking/nixlbench instead of
docs/development/benchmarking/nixlbench, preserving each check’s existing file,
content, and cross-link validation.
In @.planning/phases/33-nixlbench-overview-and-build/33-VERIFICATION.md:
- Line 17: Update the NIXLBench evidence path references in the verification
document to use docs/user-guide/benchmarking/nixlbench/ instead of
docs/development/benchmarking/nixlbench/, including the corresponding occurrence
at the additional referenced location.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-01-PLAN.md:
- Around line 7-8: Update the plan’s documentation references to use the actual
paths under docs/user-guide/benchmarking/nixlbench, including the files_modified
entry and the sibling build page link; replace ./nixlbench/build with
/docs/user-guide/benchmarking/nixlbench/build wherever it appears.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-01-SUMMARY.md:
- Around line 24-27: The summary contains inconsistent backend counts between
key-decisions and the backend enumeration. Update the affected count statements
and enumerated list in the document so they consistently reflect the actual
number of backend names linked, preserving the existing backend names and
cross-reference content.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-02-PLAN.md:
- Around line 7-10: Update every reference to the Nixlbench usage documentation
in the plan, including files_modified, artifact, and verification entries, from
docs/development/benchmarking/nixlbench/usage.md to
docs/user-guide/benchmarking/nixlbench/usage.md; leave the plan’s requirements
and execution details unchanged.
- Around line 125-128: Update the automated verification command in the plan’s
<verify> block to run from the repository root without changing directories to
the author’s absolute checkout path. Use the repository-relative docs path for
all grep checks, then run fern check from the existing fern directory via a
relative command.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-02-SUMMARY.md:
- Around line 12-13: Insert a blank line after each heading in the added
“Reading Benchmark Output” documentation, including the headings at the
referenced sections, to satisfy markdownlint MD022. Preserve all existing
content and spacing elsewhere.
- Line 13: Correct both benchmark documentation references in the summary to use
the actual location identified by the supplied stack, ensuring the audit trail
consistently points to the modified benchmark usage document rather than the
outdated location.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-RESEARCH.md:
- Around line 213-235: Update the outer Markdown fences in the communication
pattern examples around “Pairwise” and the additionally affected section to use
four backticks, preserving the inner triple-backtick bash fences and all example
content.
- Around line 280-304: Update the “Wave 0 Gaps” and phase-gate validation
language in the “Validation Architecture” section so it does not claim fern
check covers semantic requirements. Explicitly retain manual review and
content-specific checks for NB-03 through NB-06, or add executable checks for
those requirements, and ensure the phase-completion criteria require those
checks alongside fern check.
- Around line 101-107: Update all obsolete NIXLBench path references in this
research document from docs/development/benchmarking/nixlbench to
docs/user-guide/benchmarking/nixlbench, including source references, stub paths,
and validation commands. Ensure every affected occurrence, including the
sections around the cited lines, targets the supplied User Guide location.
- Around line 109-127: Update the “Backend Link Map” to add UCCL with the
`/docs/user-guide/backends/uccl` target, and reconcile the verification note and
backend count so they accurately reflect all 12 backend pages.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-VERIFICATION.md:
- Around line 47-57: Update
.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-VERIFICATION.md
lines 47-57 so the artifact and every NIXLBench key-link path reference
docs/user-guide/benchmarking/nixlbench/usage.md instead of
docs/development/benchmarking. Update
.planning/phases/35-kvbench-overview-and-build/35-CONTEXT.md lines 83-85 so its
integration paths and final-location wording use the corresponding User Guide
paths.
In @.planning/phases/35-kvbench-overview-and-build/35-01-PLAN.md:
- Around line 148-150: Replace the hardcoded absolute checkout path in the
automated verification commands near the plan’s verify sections with the
repository-relative command `cd fern && fern check`, matching the existing
portable command elsewhere in the plan. Apply this to both referenced
verification blocks.
In
@.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-01-PLAN.md:
- Around line 7-8: Update every KVBench commands page reference in the plan,
including the changed-file entry and acceptance checks, from
docs/development/benchmarking/kvbench/commands.md to
docs/user-guide/benchmarking/kvbench/commands.md. Ensure all occurrences across
the referenced sections consistently target the published path.
- Around line 43-44: Replace all author-specific absolute paths in the plan’s
execution context and verification commands with repository-relative references.
Update the commands near the referenced plan sections to run from the
repository’s fern directory, using the existing execute-plan and summary
workflow references without hard-coded checkout paths.
- Around line 339-343: Add a blank line after the final T-36-02 row in the
STRIDE table and before the closing </threat_model> tag, keeping the table
contents unchanged.
In
@.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-RESEARCH.md:
- Line 69: Remove the trailing whitespace from the “### profile” heading in the
research document, leaving the heading text unchanged so the pre-commit hook and
CI pass.
- Line 50: Fix the malformed requirements table row near the closing phase
requirements section so the KB-05 entry has leading and trailing pipes and
exactly three cells, matching the structure of the surrounding table rows.
- Around line 54-59: Update the “Target File Structure” path in the research
record to match the existing KVBench navigation target under
user-guide/benchmarking/kvbench/commands.md, and revise the adjacent
docs/index.yml verification text so it no longer claims the stale path is
already present.
In
@.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-VERIFICATION.md:
- Line 55: Add a blank line between the requirements table and the closing
</phase_requirements> tag in the verification document, keeping the table
content unchanged so Markdownlint no longer interprets the tag as a table row.
- Around line 34-43: Regenerate the verification report in 36-VERIFICATION.md
using the current docs tree under docs/user-guide/benchmarking rather than the
stale docs/development/benchmarking paths. Update the referenced source and
target paths, links, and navigation evidence while preserving the existing
verification findings for the commands.md content.
In
@.planning/phases/37-terminology-normalization-and-quality-audit/37-01-PLAN.md:
- Line 187: The automated link verification command in the plan should resolve
each Markdown link relative to its source file and verify that the resulting
target exists, rather than only printing matches with grep/head. Replace or
extend the current extraction pipeline so broken relative links cause the check
to fail while preserving the existing etcd and KVBench-to-NIXLBench checks.
- Line 138: Update the automated terminology audit command in the plan’s
<automated> check to ignore fenced code-block contents, not just lines
containing fence markers. Track Markdown fence state or use a Markdown-aware
checker for the plugin and ETCD prose checks, while preserving the existing
exclusions and PASS/diagnostic output.
In
@.planning/phases/37-terminology-normalization-and-quality-audit/37-01-SUMMARY.md:
- Around line 11-16: Update the phase entries in the dependency graph to use the
repository’s directory-style identifiers: change phase 34 to
“34-nixlbench-usage-troubleshooting-and-cross-references” and phase 36 to
“36-kvbench-commands-model-config-and-llm-examples”; leave the phase 35 entry
unchanged.
In
@.planning/phases/37-terminology-normalization-and-quality-audit/37-02-PLAN.md:
- Around line 149-153: Update the terminology verification commands in the
plan’s benchmarking sweep to use a stateful Markdown-aware filter that excludes
all content inside fenced code blocks, rather than only removing fence-marker
lines. Apply this to each grep check, including the corresponding check near the
later referenced section, while preserving the existing zero-match expectations
for prose.
- Line 164: Update the final automated verification command around the fern
check to preserve fern’s exit status when its output is piped through tail.
Enable pipefail for the command or explicitly capture and return fern’s status,
while keeping the existing truncated output behavior.
- Around line 50-51: Replace the machine-specific
/home/omrik/Projects/nixl.gitlab prefixes in the plan with repository-relative
paths and commands, including the references associated with the execution-plan
and summary templates and the additional occurrences. Preserve the intended
commands using forms such as cd fern && fern check so they work for contributors
and CI from the repository root.
In
@.planning/phases/37-terminology-normalization-and-quality-audit/37-02-SUMMARY.md:
- Line 51: In 37-02-SUMMARY.md, add a blank line immediately after the
“Accomplishments” heading and each other referenced section heading before its
following bullet or paragraph, preserving all existing content.
In
@.planning/phases/37-terminology-normalization-and-quality-audit/37-CONTEXT.md:
- Line 45: Update the D-10 requirement in the terminology normalization context
to describe a one-way cross-link: the KVBench overview must link to NIXLBench,
and no reverse NIXLBench-to-KVBench link is required.
In
@.planning/phases/37-terminology-normalization-and-quality-audit/37-VERIFICATION.md:
- Around line 59-65: Update the NIXLBench and KVBench verification commands in
the “NIXLBench uses underscores” and “KVBench uses hyphens” rows to use
fixed-string or escaped matching for the exact flag spelling, and add checks
asserting the opposite spelling is absent. Preserve the existing expected counts
and PASS criteria.
In @.planning/research/ARCHITECTURE.md:
- Around line 11-24: Update the fenced ASCII tree and YAML examples in
ARCHITECTURE.md, including the referenced sections, to use appropriate language
labels such as text and yaml. Add blank lines immediately before and after every
fenced block to satisfy markdownlint MD031, while preserving the example
contents.
- Around line 37-40: Update the benchmark documentation paths in the
“Recommended Project Structure” section of ARCHITECTURE.md from
docs/development/benchmarks/ to docs/user-guide/benchmarking/ so the documented
structure matches the repository layout.
In @.planning/research/FEATURES.md:
- Line 73: Update the Markdown in FEATURES.md to satisfy linting: replace the
“etc” usage in the CLI override arguments row with “etc.” and add an explicit
language identifier such as “text” to the ASCII diagram fence near the diagram
section. Preserve the existing table and diagram content.
In @.planning/research/SUMMARY.md:
- Around line 43-48: Replace stale benchmark documentation paths in
.planning/research/SUMMARY.md lines 43-48 and
.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-01-SUMMARY.md
lines 20-23 and 67-68 with the current docs/user-guide/benchmarking/ paths,
preserving the existing planning details while removing all
docs/development/benchmarks/ references.
In @.planning/RETROSPECTIVE.md:
- Around line 10-37: Add a blank line immediately after every Markdown section
heading in the affected retrospective content, including “What Was Built,” “What
Worked,” “What Was Inefficient,” “Patterns Established,” “Key Lessons,” and
“Cost Observations.” Preserve the existing heading text and content.
In `@docs/api-reference/rust-api.md`:
- Around line 399-405: Specify the `text` language on the Markdown fenced code
block containing the MemoryRegion/NixlDescriptor/NixlRegistration hierarchy,
leaving the diagram content unchanged.
- Around line 905-916: Update the polling loop around agent.get_xfer_status so
the XferStatus::InProgress branch yields between status checks, such as by
adding an appropriate sleep or wait delay. Preserve the existing success
handling and continue polling until XferStatus::Success.
In `@docs/data/stack-data.schema.json`:
- Around line 16-19: The version schema’s pattern and description are
inconsistent with the stated SemVer requirement. Update the `version` property
pattern to accept valid SemVer, including prerelease and build metadata while
rejecting leading-zero numeric segments, and keep its description aligned with
that behavior.
In `@docs/development/sb-api-reference.md`:
- Around line 674-690: Update the MyBackend::releaseReqH example to attempt to
abort any active transfer associated with the request handle before deleting the
MyReqHandle. Preserve the non-blocking behavior, and return an error status if
the abort attempt fails; only release the handle after the abort operation has
been initiated safely.
- Around line 537-570: Update the loadLocalMD() and unloadMD() examples so their
ownership semantics match: either have loadLocalMD() return an independently
owned metadata clone, or make unloadMD() detect registered input metadata and
avoid deleting it while still releasing owned metadata.
In `@docs/diagrams/basic-transfer/nixl_basic_transfer_01_init_dark.d2`:
- Line 1: Add the repository-standard SPDX header before the diagram content in
docs/diagrams/basic-transfer/nixl_basic_transfer_01_init_dark.d2,
docs/diagrams/remote-storage/nixl_remote_storage_02_metadata_light.d2,
docs/diagrams/gds-direct/nixl_gds_direct_02_write_light.d2, and
docs/diagrams/gds-direct/nixl_gds_direct_01_init_light.d2; leave each diagram’s
existing content unchanged.
In `@docs/diagrams/basic-transfer/nixl_basic_transfer_01_init_light.d2`:
- Line 1: Add the repository-standard SPDX copyright and Apache-2.0 license
declarations before the diagram content in
docs/diagrams/basic-transfer/nixl_basic_transfer_01_init_light.d2 and
docs/diagrams/data-flow/nixl_flow_03_transfer_dark.d2.
In `@docs/diagrams/basic-transfer/nixl_basic_transfer_02_metadata_dark.d2`:
- Line 1: Add the repository-standard SPDX header at the beginning of
docs/diagrams/basic-transfer/nixl_basic_transfer_02_metadata_dark.d2 (lines
1-1), docs/diagrams/basic-transfer/nixl_basic_transfer_03_transfer_dark.d2
(lines 1-1), fern/docs.yml (lines 1-1), and
docs/diagrams/data-flow/nixl_flow_05_scaling_dark.d2 (lines 1-1), preserving
each file’s existing content after the header.
In `@docs/diagrams/basic-transfer/nixl_basic_transfer_04_teardown_dark.d2`:
- Line 1: Add the repository-standard SPDX header before the diagram content in
docs/diagrams/basic-transfer/nixl_basic_transfer_04_teardown_dark.d2 lines 1-1,
docs/diagrams/remote-storage/nixl_remote_storage_pipeline_write_dark.d2 lines
1-1, and docs/diagrams/remote-storage/nixl_remote_storage_04_read_dark.d2 lines
1-1, preserving each diagram’s existing content after the header.
In `@docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2`:
- Around line 1-2: Add the repository-standard SPDX header containing
SPDX-FileCopyrightText and SPDX-License-Identifier: Apache-2.0 to both
docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2 (lines 1-2) and
docs/diagrams/data-flow/nixl_flow_01_init_light.d2 (lines 1-3), preserving each
diagram’s existing content after the header.
In `@docs/diagrams/data-flow/nixl_flow_04_teardown_dark.d2`:
- Line 1: Add the exact repository-required SPDX copyright header used by
passing neighboring D2 diagrams before the diagram content in
docs/diagrams/data-flow/nixl_flow_04_teardown_dark.d2 lines 1-1,
docs/diagrams/gds-direct/nixl_gds_direct_03_read_dark.d2 lines 1-1, and
docs/diagrams/etcd-metadata/nixl_etcd_metadata_04_transfer_dark.d2 lines 1-1.
In `@docs/diagrams/data-flow/nixl_flow_04_teardown_light.d2`:
- Line 1: Add the repository-standard SPDX copyright header before the title in
docs/diagrams/data-flow/nixl_flow_04_teardown_light.d2 and
docs/diagrams/remote-storage/nixl_remote_storage_03_write_light.d2, leaving the
existing diagram content unchanged.
In `@docs/diagrams/data-flow/nixl_flow_05_scaling_dark.d2`:
- Around line 56-59: Update the invalidate_remote_agent target in the scaling
sequence to reference one of the declared nodes, such as Node 1, Node 2, or Node
3, or explicitly label NodeX as an off-diagram failed peer. Keep the failure
annotation and existing styling unchanged.
In `@docs/diagrams/data-flow/nixl_flow_05_scaling_light.d2`:
- Line 1: Add the standard SPDX header block containing SPDX-FileCopyrightText
and SPDX-License-Identifier: Apache-2.0 before the diagram title in
docs/diagrams/data-flow/nixl_flow_05_scaling_light.d2,
docs/diagrams/etcd-metadata/nixl_etcd_metadata_03_fetch_dark.d2,
docs/diagrams/etcd-metadata/nixl_etcd_metadata_04_transfer_light.d2, and
docs/diagrams/gds-direct/nixl_gds_direct_02_write_dark.d2; leave the existing
diagram content unchanged.
In `@docs/diagrams/etcd-metadata/nixl_etcd_metadata_01_init_dark.d2`:
- Line 1: Add the repository-standard SPDX/copyright header before the existing
content in docs/diagrams/etcd-metadata/nixl_etcd_metadata_01_init_dark.d2,
docs/diagrams/gds-direct/nixl_gds_direct_04_verify_light.d2,
fern/snippets/env-vars-gds.mdx, and docs/index.yml. Leave each diagram, table,
and navigation block unchanged after the header.
In `@docs/diagrams/etcd-metadata/nixl_etcd_metadata_01_init_light.d2`:
- Line 1: Add the repository-standard SPDX copyright/license header before the
title in docs/diagrams/etcd-metadata/nixl_etcd_metadata_01_init_light.d2 (lines
1-1) and docs/diagrams/etcd-metadata/nixl_etcd_metadata_02_publish_light.d2
(lines 1-1), preserving each diagram title after the header.
In `@docs/diagrams/gds-direct/nixl_gds_direct_01_init_dark.d2`:
- Line 1: Prepend the repository-standard SPDX header before the existing
content in docs/diagrams/gds-direct/nixl_gds_direct_01_init_dark.d2 (lines 1-1),
docs/diagrams/basic-transfer/nixl_basic_transfer_02_metadata_light.d2 (lines
1-1), and fern/snippets/env-vars-obj.mdx (lines 1-1); leave the diagrams and
table content unchanged.
In `@docs/diagrams/gds-direct/nixl_gds_direct_03_read_light.d2`:
- Line 1: Add the exact canonical repository-required SPDX copyright/license
header before the diagram in
docs/diagrams/gds-direct/nixl_gds_direct_03_read_light.d2 at lines 1-1 and
before the table in fern/snippets/env-vars-azure-blob.mdx at lines 1-1, matching
neighboring files and using the same header in both locations.
In `@docs/diagrams/remote-storage/nixl_remote_storage_01_init_dark.d2`:
- Line 1: Add the repository-standard SPDX copyright and license header at the
beginning of the diagram source, before the existing “NIXL Remote Storage”
title. Match the header format used by neighboring diagram files.
In `@docs/diagrams/remote-storage/nixl_remote_storage_02_metadata_dark.d2`:
- Line 1: Add the repository’s required SPDX header before the diagram title in
docs/diagrams/remote-storage/nixl_remote_storage_02_metadata_dark.d2,
docs/diagrams/data-flow/nixl_flow_01_init_dark.d2, and
docs/diagrams/data-flow/nixl_flow_03_transfer_light.d2; leave the existing
diagram content unchanged.
In `@docs/diagrams/remote-storage/nixl_remote_storage_04_read_light.d2`:
- Line 1: Add the repository-approved SPDX license and copyright header before
the diagram title in each affected file:
docs/diagrams/remote-storage/nixl_remote_storage_04_read_light.d2 lines 1-1,
docs/diagrams/data-flow/nixl_flow_02_metadata_dark.d2 lines 1-1,
docs/diagrams/basic-transfer/nixl_basic_transfer_03_transfer_light.d2 lines 1-1,
and docs/diagrams/basic-transfer/nixl_basic_transfer_04_teardown_light.d2 lines
1-1. Preserve each existing diagram title and content after the header.
In `@docs/diagrams/remote-storage/nixl_remote_storage_pipeline_read_dark.d2`:
- Line 1: Add the repository-standard SPDX header at the beginning of
docs/diagrams/remote-storage/nixl_remote_storage_pipeline_read_dark.d2 (lines
1-1), docs/diagrams/remote-storage/nixl_remote_storage_01_init_light.d2 (lines
1-1), and docs/diagrams/etcd-metadata/nixl_etcd_metadata_05_invalidation_dark.d2
(lines 1-1), before each diagram’s existing content.
In `@docs/diagrams/remote-storage/nixl_remote_storage_pipeline_read_light.d2`:
- Line 1: Add the repository-standard SPDX copyright and Apache-2.0 header
before the diagram content in
docs/diagrams/remote-storage/nixl_remote_storage_pipeline_read_light.d2 (lines
1-1), docs/diagrams/gds-direct/nixl_gds_direct_04_verify_dark.d2 (lines 1-1),
docs/diagrams/etcd-metadata/nixl_etcd_metadata_02_publish_dark.d2 (lines 1-1),
and docs/diagrams/etcd-metadata/nixl_etcd_metadata_05_invalidation_light.d2
(lines 1-1).
In `@docs/examples/basic-transfer.md`:
- Line 14: Update the top-level “Initialization” section heading in the basic
transfer documentation to use `##` instead of `###`, preserving the expected
page heading hierarchy.
- Around line 395-400: Update the Expected output section in basic-transfer.md
to distinguish output by language: show “Transfer verified” and “Test done” only
for C++, no output for Python, and “Transfer and notification verified” for
Rust. Ensure the examples accurately reflect each language’s actual runtime
behavior.
- Around line 117-146: Make completion handling fail closed across all examples:
at docs/examples/basic-transfer.md lines 117-146, bound metadata and transfer
polling with sleep/backoff and raise explicit timeout errors; at lines 251-263,
abort on persistent transfer errors, bound polling, and compare transferred
bytes before reporting success; at lines 361-389, return an error if completion
or the required notification is still missing after five seconds.
In `@docs/examples/etcd-metadata-exchange.md`:
- Around line 152-165: Update the example teardown to call
A2.invalidateLocalMD() alongside A1.invalidateLocalMD(), ensuring both agents’
published etcd metadata is invalidated, including the corresponding teardown
section noted as also applying.
- Line 14: Update the markdown structure in
docs/examples/etcd-metadata-exchange.md by promoting the phase section headings,
including “Initialization” and the other matching headings, from H3 to H2. Add
the text language identifier to the expected-output code fence near the final
referenced section, preserving all content.
- Around line 92-105: Add the standard <cstdlib> header to the C++ example so
getenv and setenv are declared, leaving the existing environment configuration
logic unchanged.
In `@docs/examples/gds-direct-storage.md`:
- Line 14: Update the markdown structure in docs/examples/gds-direct-storage.md
by promoting the phase section headings, including “Initialization” and the
other affected headings, from H3 to H2. Add the `text` language identifier to
the expected-output fenced code block, including the affected block near the end
of the document.
- Around line 112-113: Update the file_path example near the os.open call to use
a runnable configurable or temporary location, or add explicit instructions to
create the parent directory before opening the file; ensure the example does not
assume /path/to already exists and is writable.
- Around line 125-145: Bound both polling flows: in
docs/examples/gds-direct-storage.md around the write and read transfer loops,
add sleep/backoff and a timeout so check_xfer_state cannot busy-poll forever; in
docs/examples/etcd-metadata-exchange.md around the getXferStatus polling and
notification wait, break on terminal errors and enforce a bounded wait. Preserve
successful DONE handling and existing failure behavior.
In `@docs/examples/nixl-ep.md`:
- Around line 19-21: Replace shell-unsafe placeholders such as “<path to UCX
install>” throughout the build commands with shell-safe /path/to/...
placeholders or quoted environment-variable values. Update the PKG_CONFIG_PATH
exports and the additional affected command examples consistently, preserving
the referenced install locations and command behavior.
In `@docs/examples/remote-storage.md`:
- Around line 43-45: Update the backend registration example around
my_agent.create_backend to explicitly check whether GDS_MT is available,
registering GDS_MT when supported and POSIX otherwise, while retaining the UCX
registration.
- Around line 97-100: Add a short time.sleep(...) delay inside the completion
polling loops using my_agent.check_remote_xfer_done, including both documented
examples, matching the existing metadata polling pattern and avoiding immediate
continue-based busy-spinning.
- Around line 102-114: Update both pipelined write handlers in the
remote-storage examples to poll each transfer handle until transfer() returns
DONE before calling send_notif(..., b"COMPLETE"). Match the completion-checking
pattern used by the basic-transfer flow, applying it to both the READ and WRITE
handles while preserving the existing transfer order.
In `@docs/getting-started/architecture.md`:
- Around line 95-104: Add an accurate language tag, such as text or bash, to the
fenced code blocks in architecture.md, including the blocks around create_agent
and the additional referenced sections. Ensure every affected fence has a
non-empty tag so markdownlint MD040 passes without changing the snippet
contents.
In `@docs/getting-started/contributing.md`:
- Line 590: Update the DCO link in the contribution documentation to use the
HTTPS DeveloperCertificate.org URL instead of HTTP, leaving the surrounding
explanatory text unchanged.
- Line 586: Update the user-facing NIXL license description to hyphenate “open
source” as “open-source,” leaving the rest of the sentence unchanged.
In `@docs/getting-started/overview.md`:
- Line 32: Update the overview diagram links in the Northbound API and
southbound plugin sections to use the documented routes: replace the C++ API
href with api-reference/cpp-api and the plugin southbound API href with
development/sb-api-reference, preserving the displayed link labels and
surrounding markup.
- Around line 23-27: Update the Backend Selection link in the Tip block to use
the registered `/nixl/user-guide/backend-selection` href instead of
`/docs/user-guide/backend-selection`, leaving the surrounding text unchanged.
In `@docs/getting-started/quick-start.md`:
- Around line 204-205: Update every polling loop in the quick-start examples,
including the loops around agent.check_remote_metadata and transfer-status
checks, to use a deadline/timeout and a short sleep or backoff between polls.
Ensure each loop exits with the existing failure or timeout behavior when the
deadline is reached, while preserving successful completion handling.
- Around line 10-18: Update the CUDA 12 and CUDA 13 pip install commands in the
getting-started guide to quote the package extras, ensuring the commands work
when copied into shells that interpret brackets as glob patterns.
In `@docs/resources/environment-variables.md`:
- Around line 55-56: Update the Prometheus telemetry quick-reference example to
set NIXL_TELEMETRY_PROMETHEUS_LOCAL=true whenever the exporter is enabled,
preventing the copied configuration from binding /metrics to all interfaces.
Keep the existing exporter settings unchanged.
In `@docs/resources/troubleshooting.md`:
- Around line 202-208: Update the GDS troubleshooting checklist to replace the
ext4/XFS-only guidance with instructions to verify compatibility between the
installed GDS version and filesystem, including parallel filesystem support, and
to run `gdscheck -p`. Keep the existing cuFile configuration and kernel-module
checks unchanged.
In `@docs/user-guide/backends/gds.md`:
- Around line 20-39: Update the “Verify GDS Installation” commands in the GDS
documentation to use the documented CUDA versioned target library directory when
checking libcufile files, and invoke gdscheck.py from the gds/tools directory
instead of the unversioned gdscheck path. Keep the surrounding verification
guidance unchanged.
In `@docs/user-guide/backends/gpunetio.md`:
- Around line 10-14: Update the GPUNetIO overview and the table’s “Best For”
description in gpunetio.md to consistently describe GPU-to-CPU VRAM ↔ DRAM
transfers, replacing the GPU-to-GPU wording while preserving the existing DOCA
GPUDirect Async context.
In `@docs/user-guide/backends/gusli.md`:
- Around line 20-31: Update the “Build from Source” instructions to include the
GUSLI installation step after `make all`, or explicitly state that the command
installs `libgusli_clnt.so` and the headers. Ensure the documented flow leaves
both artifacts available under `/usr/lib/` and `/usr/include/` before NIXL
configuration.
In `@docs/user-guide/backends/libfabric.md`:
- Around line 22-30: Update the libfabric installation commands in the
documentation to explicitly use sudo for the privileged make install and
ldconfig steps, or document an alternative user-writable installation prefix and
corresponding setup. Keep the existing build commands unchanged.
- Around line 45-49: Update the fi_info command in the libfabric documentation
to use the --list option for enumerating available providers, while retaining
--version only for reporting the libfabric version.
In `@docs/user-guide/backends/posix.md`:
- Around line 44-46: Remove io_uring_sync from the Docker seccomp syscall list
in the POSIX backend documentation and the POSIX plug-in README; retain only
io_uring_setup, io_uring_enter, and io_uring_register.
In `@docs/user-guide/backends/uccl.md`:
- Around line 18-29: Update the UCCL-P2P build commands in the “Build from
Source” section to use the repository root build.sh flow, invoking the
documented p2p target with installation enabled. Remove the direct cd uccl/p2p,
make, and sudo make install commands while preserving the repository clone and
latest-instructions link.
In `@docs/user-guide/backends/ucx.md`:
- Around line 22-27: Update the UCX version references in the guide’s
installation instructions and surrounding text from 1.20.x to the supported
1.22.x version documented in README.md, unless project guidance confirms 1.20.x
remains intentional; keep the clone and checkout commands consistent with the
chosen version.
In `@docs/user-guide/benchmarking/kvbench/build.md`:
- Around line 25-28: Update the virtual-environment setup instructions around
python3 so they explicitly use or validate a Python interpreter at version 3.12
or newer before creating venv; keep the subsequent activation, uv installation,
and uv sync steps unchanged.
In `@docs/user-guide/benchmarking/kvbench/commands.md`:
- Around line 313-363: Make the runnable DeepSeek examples internally consistent
by updating the copied outputs to match isl: 1000 and page_size: 16 in both
docs/user-guide/benchmarking/kvbench/commands.md sites (lines 313-363 and
380-430). Change each output’s ISL and Page Size values accordingly; no YAML
changes are needed.
In `@docs/user-guide/benchmarking/nixlbench/build.md`:
- Around line 84-87: Update the Meson setup commands in the benchmarking build
instructions to set the install prefix to /usr/local/nixlbench, matching the
documented PATH and LD_LIBRARY_PATH values. Apply the same prefix change to the
corresponding commands at the referenced later sections.
In `@docs/user-guide/benchmarking/nixlbench/index.md`:
- Line 6: Update the final sentence in the NIXLBench introduction to hyphenate
“well-suited” when describing its suitability for containerized and cloud-native
deployments.
In `@docs/user-guide/benchmarking/nixlbench/usage.md`:
- Line 188: Update the latency-columns description to hyphenate
“completion-checking” in the Post phase explanation, leaving the rest of the
wording unchanged.
- Around line 245-250: Update the CUDA environment setup snippet so the
LD_LIBRARY_PATH export uses the existing value only when it is set, via the
`${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}` pattern, preventing an unset variable
from adding the current directory to the library search path.
- Around line 231-235: Update the Docker build failure guidance in the
benchmarking usage section to avoid presenting “docker system prune -a” as the
default remedy. Replace it with targeted builder or build-cache cleanup, or add
a prominent warning and confirmation before any destructive cleanup command.
- Around line 15-24: Update the etcd Docker usage examples and related host 1/2
and etcdctl commands to use one consistently routable hostname or IP instead of
0.0.0.0 or the container-only etcd-server name. Ensure the advertised client and
peer URLs, worker connection examples, and etcdctl endpoint all reference that
same reachable endpoint.
- Around line 121-126: Update the NIXLBench OBJ usage example to remove the
--obj_access_key and --obj_secret_key flags and show credentials supplied
through AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, while
retaining the backend, region, and bucket configuration.
In `@docs/user-guide/building-nixl/docker.md`:
- Line 29: Update the backend documentation links in
docs/user-guide/building-nixl/docker.md lines 29-29 and
docs/getting-started/quick-start.md lines 135-135 to target the Fern route for
docs/user-guide/backends/index.md instead of /docs/user-guide/backend-selection.
In `@docs/user-guide/building-nixl/index.md`:
- Around line 8-11: Update the four build-page links in the building-nixl index
to use sibling-relative paths: ./docker, ./nixl-cpp, ./python-bindings, and
./rust-bindings, removing the duplicated building-nixl segment.
In `@docs/user-guide/building-nixl/python-bindings.md`:
- Around line 57-60: Update the expected-output fenced block containing the NIXL
log lines to specify the text language tag, changing the fence to use ```text
while leaving the output content unchanged.
- Around line 15-24: Update the Virtual Environment Setup instructions to
install the missing build prerequisites meson, ninja, and pybind11 alongside
tomlkit. Keep the existing uv-based installation flow and dependency
documentation intact.
In `@docs/user-guide/building-nixl/rust-bindings.md`:
- Around line 44-46: Update the backend links in
docs/user-guide/building-nixl/rust-bindings.md lines 44-46 and
docs/getting-started/architecture.md lines 44-46 to target the registered
canonical backend index at user-guide/backends/index.md instead of
/docs/user-guide/backend-selection.
- Around line 17-27: Update the Manual Build instructions in the Rust bindings
guide to specify the Meson build directory context before running ninja install,
using the appropriate directory-qualified command or navigation step while
preserving the existing cargo build step.
In `@docs/user-guide/etcd-metadata-exchange.md`:
- Line 90: Fix the Markdown/MDX lint errors in the untyped examples throughout
the document, including the raw etcd key-layout blocks. Add the required blank
lines around each affected code fence and its language identifier at the
referenced sections, while preserving the example content.
- Around line 175-183: Update the metadata polling example around
fetch_remote_metadata and check_remote_metadata to avoid an unbounded busy-spin:
use the fetch result directly if it indicates completion, or add a clear
deadline with a short sleep between checks and explicit handling when the
deadline is exceeded.
- Around line 95-107: Clarify the key-format documentation by explicitly
defining namespace slash normalization: state that namespace values have their
trailing slash removed before concatenation, or document that components are
joined with normalized separators. Ensure the rule matches the single-slash
examples and the default NIXL_ETCD_NAMESPACE value.
In `@docs/user-guide/telemetry.md`:
- Around line 258-268: Update the Prometheus telemetry example and corresponding
defaults in the documentation around NIXL_TELEMETRY_PROMETHEUS_LOCAL to use
true, so the default example binds only to 127.0.0.1. If retaining the false
value, add explicit authentication, TLS, firewall, or network-policy safeguards
for remote access.
In `@fern/main.css`:
- Line 408: Update the footer link rules and the other matching declarations in
main.css to replace deprecated text-wrapping properties with their current
equivalents, and add the required blank line separating custom properties from
standard declarations. Apply the same Stylelint-compliant changes at all
reported occurrences while preserving the existing wrapping behavior.
In `@fern/snippets/env-vars-libfabric.mdx`:
- Line 1: Add the repository-standard SPDX copyright and license header at the
beginning of the MDX documentation file, matching the format used by existing
documentation snippets. Keep the variable table unchanged.
---
Outside diff comments:
In `@docs/diagrams/etcd-metadata/nixl_etcd_metadata_03_fetch_light.d2`:
- Around line 1-59: Add the repository-standard SPDX copyright header to the top
of the diagram, matching the header format used by
docs/diagrams/remote-storage/nixl_remote_storage_03_write_dark.d2. Preserve the
existing sequence_diagram content unchanged.
In `@docs/diagrams/remote-storage/nixl_remote_storage_03_write_dark.d2`:
- Around line 1-69: Add the repository-required SPDX copyright and license
header to the top of the diagram file, before the existing sequence-diagram
content. Match the exact header format and attribution used by adjacent D2
documentation files, without changing the diagram definition.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 4fe35482-11ab-41bc-9c5a-d932d8d81aa6
⛔ Files ignored due to path filters (56)
docs/assets/NVIDIA_dark.svgis excluded by!**/*.svgdocs/assets/NVIDIA_light.svgis excluded by!**/*.svgdocs/assets/NVIDIA_symbol.svgis excluded by!**/*.svgdocs/assets/fonts/NVIDIASans.woff2is excluded by!**/*.woff2docs/assets/fonts/NVIDIASans_Italic.woff2is excluded by!**/*.woff2docs/assets/fonts/RobotoMono.woff2is excluded by!**/*.woff2docs/figures/basic-transfer/nixl_basic_transfer_01_init_dark.svgis excluded by!**/*.svgdocs/figures/basic-transfer/nixl_basic_transfer_01_init_light.svgis excluded by!**/*.svgdocs/figures/basic-transfer/nixl_basic_transfer_02_metadata_dark.svgis excluded by!**/*.svgdocs/figures/basic-transfer/nixl_basic_transfer_02_metadata_light.svgis excluded by!**/*.svgdocs/figures/basic-transfer/nixl_basic_transfer_03_transfer_dark.svgis excluded by!**/*.svgdocs/figures/basic-transfer/nixl_basic_transfer_03_transfer_light.svgis excluded by!**/*.svgdocs/figures/basic-transfer/nixl_basic_transfer_04_teardown_dark.svgis excluded by!**/*.svgdocs/figures/basic-transfer/nixl_basic_transfer_04_teardown_light.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_desc_hierarchy_dark.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_desc_hierarchy_light.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_01_init_dark.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_01_init_light.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_02_metadata_dark.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_02_metadata_light.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_03_transfer_dark.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_03_transfer_light.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_04_teardown_dark.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_04_teardown_light.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_05_scaling_dark.svgis excluded by!**/*.svgdocs/figures/data-flow/nixl_flow_05_scaling_light.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_01_init_dark.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_01_init_light.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_02_publish_dark.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_02_publish_light.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_03_fetch_dark.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_03_fetch_light.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_04_transfer_dark.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_04_transfer_light.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_05_invalidation_dark.svgis excluded by!**/*.svgdocs/figures/etcd-metadata/nixl_etcd_metadata_05_invalidation_light.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_01_init_dark.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_01_init_light.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_02_write_dark.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_02_write_light.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_03_read_dark.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_03_read_light.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_04_verify_dark.svgis excluded by!**/*.svgdocs/figures/gds-direct/nixl_gds_direct_04_verify_light.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_01_init_dark.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_01_init_light.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_02_metadata_dark.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_02_metadata_light.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_03_write_dark.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_03_write_light.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_04_read_dark.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_04_read_light.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_pipeline_read_dark.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_pipeline_read_light.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_pipeline_write_dark.svgis excluded by!**/*.svgdocs/figures/remote-storage/nixl_remote_storage_pipeline_write_light.svgis excluded by!**/*.svg
📒 Files selected for processing (166)
.planning/MILESTONES.md.planning/PROJECT.md.planning/RETROSPECTIVE.md.planning/ROADMAP.md.planning/STATE.md.planning/milestones/v1.1-MILESTONE-AUDIT.md.planning/milestones/v1.1-REQUIREMENTS.md.planning/milestones/v1.1-ROADMAP.md.planning/phases/32-navigation-and-directory-setup/32-01-PLAN.md.planning/phases/32-navigation-and-directory-setup/32-01-SUMMARY.md.planning/phases/32-navigation-and-directory-setup/32-02-PLAN.md.planning/phases/32-navigation-and-directory-setup/32-02-SUMMARY.md.planning/phases/32-navigation-and-directory-setup/32-CONTEXT.md.planning/phases/32-navigation-and-directory-setup/32-DISCUSSION-LOG.md.planning/phases/32-navigation-and-directory-setup/32-RESEARCH.md.planning/phases/32-navigation-and-directory-setup/32-VALIDATION.md.planning/phases/32-navigation-and-directory-setup/32-VERIFICATION.md.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md.planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md.planning/phases/33-nixlbench-overview-and-build/33-CONTEXT.md.planning/phases/33-nixlbench-overview-and-build/33-DISCUSSION-LOG.md.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md.planning/phases/33-nixlbench-overview-and-build/33-VALIDATION.md.planning/phases/33-nixlbench-overview-and-build/33-VERIFICATION.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-01-PLAN.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-01-SUMMARY.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-02-PLAN.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-02-SUMMARY.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-CONTEXT.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-DISCUSSION-LOG.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-RESEARCH.md.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-VERIFICATION.md.planning/phases/35-kvbench-overview-and-build/35-01-PLAN.md.planning/phases/35-kvbench-overview-and-build/35-CONTEXT.md.planning/phases/35-kvbench-overview-and-build/35-DISCUSSION-LOG.md.planning/phases/35-kvbench-overview-and-build/35-RESEARCH.md.planning/phases/35-kvbench-overview-and-build/35-VERIFICATION.md.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-01-PLAN.md.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-01-SUMMARY.md.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-CONTEXT.md.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-DISCUSSION-LOG.md.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-RESEARCH.md.planning/phases/36-kvbench-commands-model-config-and-llm-examples/36-VERIFICATION.md.planning/phases/37-terminology-normalization-and-quality-audit/37-01-PLAN.md.planning/phases/37-terminology-normalization-and-quality-audit/37-01-SUMMARY.md.planning/phases/37-terminology-normalization-and-quality-audit/37-02-PLAN.md.planning/phases/37-terminology-normalization-and-quality-audit/37-02-SUMMARY.md.planning/phases/37-terminology-normalization-and-quality-audit/37-CONTEXT.md.planning/phases/37-terminology-normalization-and-quality-audit/37-DISCUSSION-LOG.md.planning/phases/37-terminology-normalization-and-quality-audit/37-VERIFICATION.md.planning/research/ARCHITECTURE.md.planning/research/FEATURES.md.planning/research/PITFALLS.md.planning/research/STACK.md.planning/research/SUMMARY.mddocs/api-reference/cpp-api.mddocs/api-reference/device-api.mddocs/api-reference/northbound-api.mddocs/api-reference/python-api.mddocs/api-reference/rust-api.mddocs/data/stack-data.jsondocs/data/stack-data.schema.jsondocs/development/building-a-backend-plugin.mddocs/development/sb-api-reference.mddocs/diagrams/basic-transfer/nixl_basic_transfer_01_init_dark.d2docs/diagrams/basic-transfer/nixl_basic_transfer_01_init_light.d2docs/diagrams/basic-transfer/nixl_basic_transfer_02_metadata_dark.d2docs/diagrams/basic-transfer/nixl_basic_transfer_02_metadata_light.d2docs/diagrams/basic-transfer/nixl_basic_transfer_03_transfer_dark.d2docs/diagrams/basic-transfer/nixl_basic_transfer_03_transfer_light.d2docs/diagrams/basic-transfer/nixl_basic_transfer_04_teardown_dark.d2docs/diagrams/basic-transfer/nixl_basic_transfer_04_teardown_light.d2docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2docs/diagrams/data-flow/nixl_desc_hierarchy_light.d2docs/diagrams/data-flow/nixl_flow_01_init_dark.d2docs/diagrams/data-flow/nixl_flow_01_init_light.d2docs/diagrams/data-flow/nixl_flow_02_metadata_dark.d2docs/diagrams/data-flow/nixl_flow_02_metadata_light.d2docs/diagrams/data-flow/nixl_flow_03_transfer_dark.d2docs/diagrams/data-flow/nixl_flow_03_transfer_light.d2docs/diagrams/data-flow/nixl_flow_04_teardown_dark.d2docs/diagrams/data-flow/nixl_flow_04_teardown_light.d2docs/diagrams/data-flow/nixl_flow_05_scaling_dark.d2docs/diagrams/data-flow/nixl_flow_05_scaling_light.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_01_init_dark.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_01_init_light.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_02_publish_dark.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_02_publish_light.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_03_fetch_dark.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_03_fetch_light.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_04_transfer_dark.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_04_transfer_light.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_05_invalidation_dark.d2docs/diagrams/etcd-metadata/nixl_etcd_metadata_05_invalidation_light.d2docs/diagrams/gds-direct/nixl_gds_direct_01_init_dark.d2docs/diagrams/gds-direct/nixl_gds_direct_01_init_light.d2docs/diagrams/gds-direct/nixl_gds_direct_02_write_dark.d2docs/diagrams/gds-direct/nixl_gds_direct_02_write_light.d2docs/diagrams/gds-direct/nixl_gds_direct_03_read_dark.d2docs/diagrams/gds-direct/nixl_gds_direct_03_read_light.d2docs/diagrams/gds-direct/nixl_gds_direct_04_verify_dark.d2docs/diagrams/gds-direct/nixl_gds_direct_04_verify_light.d2docs/diagrams/remote-storage/nixl_remote_storage_01_init_dark.d2docs/diagrams/remote-storage/nixl_remote_storage_01_init_light.d2docs/diagrams/remote-storage/nixl_remote_storage_02_metadata_dark.d2docs/diagrams/remote-storage/nixl_remote_storage_02_metadata_light.d2docs/diagrams/remote-storage/nixl_remote_storage_03_write_dark.d2docs/diagrams/remote-storage/nixl_remote_storage_03_write_light.d2docs/diagrams/remote-storage/nixl_remote_storage_04_read_dark.d2docs/diagrams/remote-storage/nixl_remote_storage_04_read_light.d2docs/diagrams/remote-storage/nixl_remote_storage_pipeline_read_dark.d2docs/diagrams/remote-storage/nixl_remote_storage_pipeline_read_light.d2docs/diagrams/remote-storage/nixl_remote_storage_pipeline_write_dark.d2docs/diagrams/remote-storage/nixl_remote_storage_pipeline_write_light.d2docs/diagrams/render.shdocs/examples/basic-transfer.mddocs/examples/etcd-metadata-exchange.mddocs/examples/gds-direct-storage.mddocs/examples/nixl-ep.mddocs/examples/remote-storage.mddocs/examples/telemetry-reader.mddocs/getting-started/.gitkeepdocs/getting-started/architecture.mddocs/getting-started/contributing.mddocs/getting-started/overview.mddocs/getting-started/quick-start.mddocs/index.ymldocs/resources/environment-variables.mddocs/resources/troubleshooting.mddocs/scripts/generate-stack-data.mjsdocs/user-guide/backends/azure-blob.mddocs/user-guide/backends/gds-mt.mddocs/user-guide/backends/gds.mddocs/user-guide/backends/gpunetio.mddocs/user-guide/backends/gusli.mddocs/user-guide/backends/hf3fs.mddocs/user-guide/backends/index.mddocs/user-guide/backends/libfabric.mddocs/user-guide/backends/mooncake.mddocs/user-guide/backends/obj.mddocs/user-guide/backends/posix.mddocs/user-guide/backends/uccl.mddocs/user-guide/backends/ucx.mddocs/user-guide/benchmarking/kvbench/build.mddocs/user-guide/benchmarking/kvbench/commands.mddocs/user-guide/benchmarking/kvbench/index.mddocs/user-guide/benchmarking/nixlbench/build.mddocs/user-guide/benchmarking/nixlbench/index.mddocs/user-guide/benchmarking/nixlbench/usage.mddocs/user-guide/building-nixl/docker.mddocs/user-guide/building-nixl/index.mddocs/user-guide/building-nixl/nixl-cpp.mddocs/user-guide/building-nixl/python-bindings.mddocs/user-guide/building-nixl/rust-bindings.mddocs/user-guide/etcd-metadata-exchange.mddocs/user-guide/telemetry.mdfern/components/CustomFooter.tsxfern/docs.ymlfern/fern.config.jsonfern/main.cssfern/snippets/env-vars-azure-blob.mdxfern/snippets/env-vars-gds.mdxfern/snippets/env-vars-libfabric.mdxfern/snippets/env-vars-mooncake.mdxfern/snippets/env-vars-obj.mdxfern/snippets/env-vars-ucx.mdx
| **Shipped:** | ||
|
|
||
| - Getting Started section (Overview, Architecture, Quick Start, Contributing) | ||
| - User Guide: all 13 backends, ETCD metadata exchange, telemetry |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the backend count.
This says “all 13 backends,” but docs/index.yml lists 12 backend pages and docs/getting-started/architecture.md says NIXL ships with 12 backends. Update the count or document the additional backend explicitly.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/MILESTONES.md at line 26, Update the backend count in the User
Guide milestone entry to 12, matching docs/index.yml and
docs/getting-started/architecture.md; only document an additional backend
instead if one is actually intended and added explicitly.
|
|
||
| ## Minor Observations | ||
|
|
||
| - Backend list discrepancy: NIXLBench overview lists 12 backends; `--backend` CLI flag accepts 9 (Libfabric, Azure Blob, UCCL-P2P not in CLI). Likely intentional — Features list describes NIXL ecosystem, CLI table documents actual flag values. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Reconcile the backend count with the overview.
The current NIXLBench overview enumerates 4 network and 7 storage backends (11 total), and does not list UCCL-P2P. Update this audit note or the overview so the discrepancy is based on the same source set.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/milestones/v1.1-MILESTONE-AUDIT.md at line 129, Reconcile the
backend discrepancy between the NIXLBench overview and the --backend CLI audit
note by using the same backend source set and count in both. Update the audit
entry to reflect the overview’s 4 network plus 7 storage backends, including
whether UCCL-P2P is present, or revise the overview to match the documented CLI
values.
Comment on lines
+7
to
+11
| files_modified: | ||
| - docs/development/benchmarking/nixlbench/index.md | ||
| - docs/development/benchmarking/nixlbench/usage.md | ||
| - docs/development/benchmarking/kvbench/index.md | ||
| - docs/development/benchmarking/kvbench/commands.md |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Align the plan paths with the actual benchmark documentation tree.
This plan targets docs/development/benchmarking/..., while the benchmark pages in this PR are under docs/user-guide/benchmarking/.... As written, Tasks 1–2 can create duplicate, unlinked stubs and the declared navigation key links will not describe the current tree. Update all file paths, verification commands, and acceptance criteria consistently.
Also applies to: 35-43
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/32-navigation-and-directory-setup/32-02-PLAN.md around
lines 7 - 11, Update the benchmark documentation paths throughout plan phases 32
and 35–43 from docs/development/benchmarking/... to the actual
docs/user-guide/benchmarking/... tree. Adjust the related verification commands,
navigation-key references, and acceptance criteria consistently so they target
the existing pages and do not create duplicate stubs.
Comment on lines
+53
to
+55
| <execution_context> | ||
| @/home/omrik/Projects/nixl.gitlab/.claude/get-shit-done/workflows/execute-plan.md | ||
| @/home/omrik/Projects/nixl.gitlab/.claude/get-shit-done/templates/summary.md |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Replace absolute local paths in the execution context.
@/home/omrik/Projects/nixl.gitlab/... will not resolve for other contributors or CI. Use repository-relative references or a documented workflow path that exists in every checkout.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/32-navigation-and-directory-setup/32-02-PLAN.md around
lines 53 - 55, Update the execution_context entries in the plan to remove the
machine-specific /home/omrik/Projects/nixl.gitlab prefix, using
repository-relative paths or the documented workflow location that resolves
consistently for all checkouts.
Comment on lines
+9
to
+12
| - docs/development/benchmarking/nixlbench/index.md | ||
| - docs/development/benchmarking/nixlbench/usage.md | ||
| - docs/development/benchmarking/kvbench/index.md | ||
| - docs/development/benchmarking/kvbench/commands.md |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Update the summary to reflect the current benchmarking paths.
This summary references docs/development/benchmarking/..., while the current documentation is under docs/user-guide/benchmarking/.... The “all paths resolve” claim is therefore stale and can mislead future audits. Update these paths or explicitly document the directory move.
Also applies to: 23-23, 38-46
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/32-navigation-and-directory-setup/32-02-SUMMARY.md around
lines 9 - 12, Update the benchmarking file paths listed in the summary and the
“all paths resolve” claim to use the current docs/user-guide/benchmarking
directory, including all references covered by the additional affected lines. If
documenting the move instead, clearly record the old-to-new directory transition
so future path audits remain accurate.
Comment on lines
+20
to
+31
| ### Build from Source | ||
|
|
||
| ```bash | ||
| git clone https://github.com/nvidia/gusli.git | ||
| cd gusli | ||
| make all BUILD_RELEASE=1 BUILD_FOR_UNITEST=0 VERBOSE=1 ALLOW_USE_URING=0 | ||
| ``` | ||
|
|
||
| Ensure that `libgusli_clnt.so` is installed under `/usr/lib/` and GUSLI headers are installed under `/usr/include/gusli_*.hpp`. | ||
|
|
||
| <Warning> | ||
| GUSLI must be built before NIXL. The NIXL build system detects the GUSLI library at configure time. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## docs/user-guide/backends/gusli.md (selected lines)\n'
nl -ba docs/user-guide/backends/gusli.md | sed -n '1,120p'
printf '\n## Search for GUSLI install/build references\n'
rg -n --hidden --no-ignore-vcs -S "libgusli_clnt\.so|gusli_.*\.hpp|BUILD_RELEASE=1|ALLOW_USE_URING=0|make all|install" docs . 2>/dev/null | sed -n '1,220p'Repository: ai-dynamo/nixl
Length of output: 247
🏁 Script executed:
#!/bin/bash
echo hiRepository: ai-dynamo/nixl
Length of output: 155
🌐 Web query:
GUSLI build install libgusli_clnt.so headers make all install documentation
💡 Result:
GUSLI (G3+ User Space Access Library) is an open-source C++ library developed by NVIDIA that encapsulates I/O operations for local block devices or files [1][2]. To build and install GUSLI and its client library (libgusli_clnt.so) and headers, follow these steps [3][4]: 1. Clone the repository: git clone https://github.com/nvidia/gusli.git cd gusli 2. Build the project: Execute the make command with appropriate flags to compile the library. A commonly used build configuration for production integration is [5][4]: make all BUILD_RELEASE=1 BUILD_FOR_UNITEST=0 VERBOSE=1 ALLOW_USE_URING=0 3. Install the library and headers: While the GUSLI Makefile includes an automated install target [6], typical manual deployment involves copying the artifacts to standard system directories [3][7]: sudo cp libgusli_clnt.so /usr/lib/ sudo cp gusli_*.hpp /usr/include/ sudo ldconfig Note on Documentation: The project provides C++ header files (e.g., gusli_client_api.hpp and gusli_server_api.hpp) which serve as the primary API documentation [6]. Detailed usage examples, particularly for integrating GUSLI with other projects like NIXL, can be found in the README files and source code of dependent repositories [8][3][7]. Important: Ensure you build GUSLI before building any dependent software that requires it [8][4]. Warning: Please distinguish this technical software library from the unrelated GUSLI music service, which is a separate consumer-facing application [9][10].
Citations:
- 1: https://github.com/NVIDIA/GUSLI
- 2: https://github.com/NVIDIA/GUSLI/blob/main/CONTRIBUTING.md
- 3: DemingCheng@c6c0983
- 4: DemingCheng@1ee9e6d
- 5: https://github.com/NVIDIA/GUSLI/blob/main/80scripts/integration_with_nixl.sh
- 6: https://github.com/NVIDIA/GUSLI/blob/main/Makefile
- 7: https://github.com/ai-dynamo/nixl/blob/main/benchmark/nixlbench/README.md
- 8: https://github.com/ai-dynamo/nixl/blob/main/src/plugins/gusli/README.md
- 9: https://gusli.net/pdf/rp_pl_wn_ru_2024-12-04.pdf
- 10: https://gusli.net/en/voprosy-i-otvety
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## docs/user-guide/backends/gusli.md\n'
sed -n '1,120p' docs/user-guide/backends/gusli.md
printf '\n## local references to GUSLI install/headers\n'
rg -n --hidden --no-ignore-vcs -S "libgusli_clnt\.so|gusli_.*\.hpp|BUILD_RELEASE=1|ALLOW_USE_URING=0|make all|make install|install target" . 2>/dev/null | sed -n '1,240p'Repository: ai-dynamo/nixl
Length of output: 6192
Add the GUSLI install step. The source-build snippet stops at make all, but the next lines assume libgusli_clnt.so and the headers are already installed for NIXL’s configure step. Show the install command, or state that make all installs them, so the setup is complete.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/backends/gusli.md` around lines 20 - 31, Update the “Build
from Source” instructions to include the GUSLI installation step after `make
all`, or explicitly state that the command installs `libgusli_clnt.so` and the
headers. Ensure the documented flow leaves both artifacts available under
`/usr/lib/` and `/usr/include/` before NIXL configuration.
Comment on lines
+25
to
+28
| python3 -m venv venv | ||
| source venv/bin/activate | ||
| pip install uv | ||
| uv sync --active |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use an interpreter that satisfies the documented Python requirement.
python3 may resolve to Python older than 3.12, causing the setup to fail despite following the instructions. Add an explicit version check or invoke a supported interpreter before creating the virtual environment.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/benchmarking/kvbench/build.md` around lines 25 - 28, Update
the virtual-environment setup instructions around python3 so they explicitly use
or validate a Python interpreter at version 3.12 or newer before creating venv;
keep the subsequent activation, uv installation, and uv sync steps unchanged.
Comment on lines
+84
to
+87
| ```bash | ||
| cd benchmark/nixlbench | ||
| meson setup build -Dnixl_path=/usr/local/nixl --buildtype=release | ||
| cd build && ninja && sudo ninja install |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make the native install prefix match the documented environment variables.
The build command uses the default /usr/local prefix, but the post-install instructions reference /usr/local/nixlbench. Following these steps will install files under different paths from those exported in PATH and LD_LIBRARY_PATH.
Proposed fix
-meson setup build -Dnixl_path=/usr/local/nixl --buildtype=release
+meson setup build -Dnixl_path=/usr/local/nixl -Dprefix=/usr/local/nixlbench --buildtype=releaseAlso applies to: 94-96, 104-106
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/benchmarking/nixlbench/build.md` around lines 84 - 87, Update
the Meson setup commands in the benchmarking build instructions to set the
install prefix to /usr/local/nixlbench, matching the documented PATH and
LD_LIBRARY_PATH values. Apply the same prefix change to the corresponding
commands at the referenced later sections.
| description: A benchmarking tool for measuring NIXL data transfer performance across network and storage backends with etcd-based coordination. | ||
| --- | ||
|
|
||
| NIXLBench is a benchmarking tool for the NVIDIA Inference Xfer Library (NIXL) that measures data transfer performance across distributed computing environments. It enables developers to evaluate throughput and latency for point-to-point communication, multi-node transfers, and storage I/O by exercising the full range of NIXL backends. Workers coordinate through [etcd](../../etcd-metadata-exchange.md), making NIXLBench well suited for containerized and cloud-native deployments. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Hyphenate “well-suited.”
Use “making NIXLBench well-suited for containerized and cloud-native deployments.”
🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: Use a hyphen to join words.
Context: ...data-exchange.md), making NIXLBench well suited for containerized and cloud-nativ...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/benchmarking/nixlbench/index.md` at line 6, Update the final
sentence in the NIXLBench introduction to hyphenate “well-suited” when
describing its suitability for containerized and cloud-native deployments.
Source: Linters/SAST tools
| </Tip> | ||
|
|
||
| <Note> | ||
| For backend-specific build instructions, see [NIXL Backends](/docs/user-guide/backend-selection). |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Point backend links at the shipped backend section.
Both pages link to /docs/user-guide/backend-selection, but the supplied documentation tree contains docs/user-guide/backends/index.md. Update both links to the actual Fern route.
docs/user-guide/building-nixl/docker.md#L29-L29: replace the backend-selection target.docs/getting-started/quick-start.md#L135-L135: replace the backend-selection target.
📍 Affects 2 files
docs/user-guide/building-nixl/docker.md#L29-L29(this comment)docs/getting-started/quick-start.md#L135-L135
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/building-nixl/docker.md` at line 29, Update the backend
documentation links in docs/user-guide/building-nixl/docker.md lines 29-29 and
docs/getting-started/quick-start.md lines 135-135 to target the Fern route for
docs/user-guide/backends/index.md instead of /docs/user-guide/backend-selection.
Comment on lines
+3
to
+4
| **Archived:** 2026-04-07 | ||
| **Status:** SHIPPED |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
set -e
wc -l .planning/milestones/v1.1-REQUIREMENTS.md
printf '\n--- lines 1-120 ---\n'
cat -n .planning/milestones/v1.1-REQUIREMENTS.md | sed -n '1,120p'Repository: ai-dynamo/nixl
Length of output: 5488
🏁 Script executed:
set -e
python3 - <<'PY'
from pathlib import Path
p = Path('.planning/milestones/v1.1-REQUIREMENTS.md')
text = p.read_text()
for needle in ['SHIPPED', 'Pending', 'Complete', 'KB-03', 'KB-04', 'KB-05', 'Archived:']:
print(f'-- {needle} --')
for i, line in enumerate(text.splitlines(), 1):
if needle in line:
print(f'{i}: {line}')
PYRepository: ai-dynamo/nixl
Length of output: 1637
🏁 Script executed:
set -e
python3 - <<'PY'
from pathlib import Path
p = Path('.planning/milestones/v1.1-REQUIREMENTS.md')
for i, line in enumerate(p.read_text().splitlines(), 1):
if 1 <= i <= 90:
print(f"{i:>3}: {line}")
PYRepository: ai-dynamo/nixl
Length of output: 5268
Reconcile the archived status with the requirement state. .planning/milestones/v1.1-REQUIREMENTS.md:3-4,58-77 marks v1.1 as SHIPPED, but most requirements in the traceability table are still Pending. Update the table or change the archive status so the milestone metadata stays consistent.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/milestones/v1.1-REQUIREMENTS.md around lines 3 - 4, Reconcile the
milestone metadata in v1.1-REQUIREMENTS.md: either update the traceability table
entries in the requirements section to reflect completed delivery, or change the
top-level Archived/Status metadata from SHIPPED to match the remaining Pending
requirements. Ensure the final metadata and requirement states consistently
describe the milestone.
Comment on lines
+7
to
+8
| - docs/development/benchmarking/nixlbench/index.md | ||
| - docs/development/benchmarking/nixlbench/build.md |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Align planning evidence with the actual documentation paths.
.planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md#L7-L8: Replacedocs/development/benchmarking/nixlbench/...with the actualdocs/user-guide/benchmarking/nixlbench/...paths..planning/phases/35-kvbench-overview-and-build/35-VERIFICATION.md#L28-L29: Update the navigation evidence todocs/user-guide/benchmarking/kvbench/build.md..planning/phases/35-kvbench-overview-and-build/35-VERIFICATION.md#L37-L46: Correct the KVBench artifact and link-verification paths, then rerun the report.
📍 Affects 2 files
.planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md#L7-L8(this comment).planning/phases/35-kvbench-overview-and-build/35-VERIFICATION.md#L28-L29.planning/phases/35-kvbench-overview-and-build/35-VERIFICATION.md#L37-L46
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md around
lines 7 - 8, Planning evidence references outdated documentation and artifact
paths. In .planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md
lines 7-8, replace the Nixlbench paths with
docs/user-guide/benchmarking/nixlbench/index.md and build.md; in
.planning/phases/35-kvbench-overview-and-build/35-VERIFICATION.md lines 28-29,
update navigation evidence to docs/user-guide/benchmarking/kvbench/build.md; in
the same file lines 37-46, correct the KVBench artifact and link-verification
paths and rerun the verification report.
Comment on lines
+22
to
+23
| ### Navigation Update (docs/index.yml) | ||
| Added `Building NIXLBench` page entry under Developer Guide > Benchmarking > NIXLBench, positioned before the existing `Usage and Troubleshooting` entry. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add blank lines after these headings.
markdownlint-cli2 reports MD022 violations because the headings at Lines 22, 25, 33, and 41 are not followed by a blank line.
Also applies to: 25-26, 33-34, 41-42
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 22-22: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/33-nixlbench-overview-and-build/33-01-SUMMARY.md around
lines 22 - 23, Add a blank line immediately after each affected Markdown heading
at lines 22, 25, 33, and 41 in the summary document, preserving all existing
content and navigation details.
Source: Linters/SAST tools
Comment on lines
+24
to
+27
| key-decisions: | ||
| - "All 11 backend names linked on first mention in the etcd Coordination paragraph for compact cross-referencing" | ||
| - "CLI tables split into Core Configuration (6 flags) and Memory/Transfer Configuration (12 flags) per plan spec" | ||
| - "Troubleshooting uses Symptoms/Resolution format for scannable problem-solving" |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Reconcile the backend count.
The summary claims 11 backend links at Line [25], but claims 10 at Line [55] and enumerates ten names. Use one count consistently.
Also applies to: 53-56
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-01-SUMMARY.md
around lines 24 - 27, The summary contains inconsistent backend counts between
key-decisions and the backend enumeration. Update the affected count statements
and enumerated list in the document so they consistently reflect the actual
number of backend names linked, preserving the existing backend names and
cross-reference content.
Comment on lines
+12
to
+13
| ## What Was Built | ||
| Added a "Reading Benchmark Output" section to `docs/development/benchmarking/nixlbench/usage.md` between CLI Options and Troubleshooting. The section documents all 12 output columns with units and descriptions, includes a `<Note>` callout explaining multi-worker pairwise extra columns, and explains the three latency phases (Prep, Tx, Post). |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add blank lines around headings.
markdownlint reports MD022 at Lines 12, 17, 20, 23, and 26. Insert a blank line after each heading.
Also applies to: 17-18, 20-21, 23-24, 26-27
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 12-12: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-02-SUMMARY.md
around lines 12 - 13, Insert a blank line after each heading in the added
“Reading Benchmark Output” documentation, including the headings at the
referenced sections, to satisfy markdownlint MD022. Preserve all existing
content and spacing elsewhere.
Source: Linters/SAST tools
Comment on lines
+15
to
+24
| - **tomlkit**: installed below via uv or pip | ||
| - **PyTorch**: [pytorch.org](https://pytorch.org/get-started/locally/) | ||
|
|
||
| ## Virtual Environment Setup | ||
|
|
||
| ```bash | ||
| uv venv .venv --python 3.12 | ||
| source .venv/bin/activate | ||
| uv pip install tomlkit | ||
| ``` |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== File outline ==\n'
ast-grep outline docs/user-guide/building-nixl/python-bindings.md --view expanded || true
printf '\n== Relevant lines ==\n'
cat -n docs/user-guide/building-nixl/python-bindings.md | sed -n '1,120p'
printf '\n== Search for build-tool prerequisites ==\n'
rg -n --hidden --glob '!**/.git/**' -e 'meson|ninja|pybind11|tomlkit|uv pip install|pip install' docs . || trueRepository: ai-dynamo/nixl
Length of output: 44753
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== pyproject build requirements ==\n'
cat -n pyproject.toml | sed -n '1,80p'
printf '\n== Python binding meson file ==\n'
cat -n src/bindings/python/meson.build | sed -n '1,120p'
printf '\n== Nearby docs for the same build path ==\n'
cat -n docs/user-guide/building-nixl/nixl-cpp.md | sed -n '1,80p'Repository: ai-dynamo/nixl
Length of output: 4946
Add the missing Python build prerequisites
tomlkit isn’t enough here: this flow later runs meson/ninja, and the Meson build also looks for pybind11. Install them in the venv setup step.
Suggested fix
-uv pip install tomlkit
+uv pip install meson ninja pybind11 tomlkit📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **tomlkit**: installed below via uv or pip | |
| - **PyTorch**: [pytorch.org](https://pytorch.org/get-started/locally/) | |
| ## Virtual Environment Setup | |
| ```bash | |
| uv venv .venv --python 3.12 | |
| source .venv/bin/activate | |
| uv pip install tomlkit | |
| ``` | |
| - **tomlkit**: installed below via uv or pip | |
| - **PyTorch**: [pytorch.org](https://pytorch.org/get-started/locally/) | |
| ## Virtual Environment Setup | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/building-nixl/python-bindings.md` around lines 15 - 24,
Update the Virtual Environment Setup instructions to install the missing build
prerequisites meson, ninja, and pybind11 alongside tomlkit. Keep the existing
uv-based installation flow and dependency documentation intact.
Source: MCP tools
Comment on lines
+57
to
+60
| ``` | ||
| NIXL INFO _api.py:363 Backend UCX was instantiated | ||
| NIXL INFO _api.py:253 Initialized NIXL agent: agent1 | ||
| ``` |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add a language tag to the expected-output fence.
Use text for this output-only code block to satisfy the reported MD040 lint warning.
Proposed fix
-```
+```text📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ``` | |
| NIXL INFO _api.py:363 Backend UCX was instantiated | |
| NIXL INFO _api.py:253 Initialized NIXL agent: agent1 | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 57-57: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/building-nixl/python-bindings.md` around lines 57 - 60,
Update the expected-output fenced block containing the NIXL log lines to specify
the text language tag, changing the fence to use ```text while leaving the
output content unchanged.
Source: Linters/SAST tools
Comment on lines
+17
to
+27
| ## Manual Build | ||
|
|
||
| ```bash | ||
| cargo build --release | ||
| ``` | ||
|
|
||
| Install the NIXL C++ library (required by the Rust bindings): | ||
|
|
||
| ```bash | ||
| ninja install | ||
| ``` |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== rust-bindings.md excerpt =="
sed -n '1,120p' docs/user-guide/building-nixl/rust-bindings.md | cat -n
echo
echo "== docs index references =="
if [ -f docs/index.yml ]; then
rg -n "backend-selection|building-nixl|rust-bindings" docs/index.yml docs -g '*.md' -g '*.yml' || true
fi
echo
echo "== search for backend-selection path =="
rg -n "/docs/user-guide/backend-selection|backend-selection" docs -g '*.md' -g '*.yml' || true
echo
echo "== search for ninja install context =="
rg -n "ninja install|meson setup|builddir|build directory|meson" docs/user-guide/building-nixl -g '*.md' || trueRepository: ai-dynamo/nixl
Length of output: 10491
🏁 Script executed:
#!/bin/bash
set -euo pipefail
sed -n '1,120p' docs/user-guide/building-nixl/rust-bindings.md | cat -nRepository: ai-dynamo/nixl
Length of output: 1149
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Rust binding files =="
git ls-files | rg '^bindings/rust/|^docs/user-guide/building-nixl/rust-bindings.md$'
echo
echo "== Cargo manifest / build script / sources =="
for f in \
bindings/rust/Cargo.toml \
bindings/rust/build.rs \
bindings/rust/src/lib.rs \
bindings/rust/README.md
do
if [ -f "$f" ]; then
echo "--- $f ---"
sed -n '1,220p' "$f" | cat -n
echo
fi
doneRepository: ai-dynamo/nixl
Length of output: 271
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== C++ build doc excerpt =="
sed -n '1,120p' docs/user-guide/building-nixl/nixl-cpp.md | cat -n
echo
echo "== building-nixl index excerpt =="
sed -n '1,120p' docs/user-guide/building-nixl/index.md | cat -nRepository: ai-dynamo/nixl
Length of output: 3854
Add the build-directory context for ninja install. The manual path should show which Meson build directory to use before the install step.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/building-nixl/rust-bindings.md` around lines 17 - 27, Update
the Manual Build instructions in the Rust bindings guide to specify the Meson
build directory context before running ninja install, using the appropriate
directory-qualified command or navigation step while preserving the existing
cargo build step.
Comment on lines
+44
to
+46
| <Note> | ||
| For backend-specific build instructions, see [NIXL Backends](/docs/user-guide/backend-selection). | ||
| </Note> |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Point both backend links to the registered page.
Both pages link to /docs/user-guide/backend-selection, while docs/index.yml registers the backend page at user-guide/backends/index.md.
docs/user-guide/building-nixl/rust-bindings.md#L44-L46: update the backend link to the canonical backend index.docs/getting-started/architecture.md#L44-L46: update the backend link to the canonical backend index.
📍 Affects 2 files
docs/user-guide/building-nixl/rust-bindings.md#L44-L46(this comment)docs/getting-started/architecture.md#L44-L46
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/building-nixl/rust-bindings.md` around lines 44 - 46, Update
the backend links in docs/user-guide/building-nixl/rust-bindings.md lines 44-46
and docs/getting-started/architecture.md lines 44-46 to target the registered
canonical backend index at user-guide/backends/index.md instead of
/docs/user-guide/backend-selection.
Comment on lines
+258
to
+268
| ```bash | ||
| export NIXL_TELEMETRY_ENABLE=true | ||
| export NIXL_TELEMETRY_EXPORTER=prometheus | ||
| export NIXL_TELEMETRY_PROMETHEUS_PORT=9090 # Default port | ||
| export NIXL_TELEMETRY_PROMETHEUS_LOCAL=false # Bind to all interfaces | ||
| ``` | ||
|
|
||
| | Variable | Default | Description | | ||
| |----------|---------|-------------| | ||
| | `NIXL_TELEMETRY_PROMETHEUS_PORT` | `9090` | HTTP listen port for the metrics endpoint | | ||
| | `NIXL_TELEMETRY_PROMETHEUS_LOCAL` | `false` | When `true`, binds to `127.0.0.1` only; when `false`, binds to `0.0.0.0` | |
Contributor
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Do not present an unauthenticated all-interface bind as the default example.
NIXL_TELEMETRY_PROMETHEUS_LOCAL=false binds Prometheus to 0.0.0.0, while this guide documents no authentication, TLS, firewall, or network-policy requirements. Use true for the local example, or add explicit safeguards for intentional remote scraping.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/telemetry.md` around lines 258 - 268, Update the Prometheus
telemetry example and corresponding defaults in the documentation around
NIXL_TELEMETRY_PROMETHEUS_LOCAL to use true, so the default example binds only
to 127.0.0.1. If retaining the false value, add explicit authentication, TLS,
firewall, or network-policy safeguards for remote access.
Comment on lines
+40
to
+42
| <execution_context> | ||
| @/home/omrik/Projects/nixl.gitlab/.claude/get-shit-done/workflows/execute-plan.md | ||
| @/home/omrik/Projects/nixl.gitlab/.claude/get-shit-done/templates/summary.md |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win
Remove the host-specific execution context.
@/home/omrik/Projects/nixl.gitlab/... only resolves on one workstation. Use a repository-relative path or a documented tool alias so other contributors and CI can execute the plan.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/32-navigation-and-directory-setup/32-01-PLAN.md around
lines 40 - 42, Update the execution_context block in the plan to replace the
workstation-specific absolute references with repository-relative paths or
documented tool aliases, while preserving the existing workflow and summary
template references.
Comment on lines
+47
to
+62
| ## 3. Directory Naming Discrepancy | ||
|
|
||
| **Critical finding:** CONTEXT.md D-05 says `docs/development/benchmarking/` but ROADMAP.md success criteria #2 and REQUIREMENTS.md NAV-02 say `docs/development/benchmarks/`. ARCHITECTURE.md also uses `benchmarks/`. | ||
|
|
||
| **Resolution:** Follow CONTEXT.md (user decisions), which says `benchmarking/`. The ROADMAP and REQUIREMENTS were written before the discuss-phase captured user preferences. CONTEXT.md D-01 explicitly says `section: Benchmarking` (not "Benchmarks"), and D-05 explicitly says `docs/development/benchmarking/`. The directory name `benchmarking/` is consistent with the section label `Benchmarking`. | ||
|
|
||
| ## 4. Stub File Requirements | ||
|
|
||
| Per CONTEXT.md D-06 through D-08, exactly 4 stub files: | ||
|
|
||
| | File | Title (D-08) | Purpose | | ||
| |------|--------------|---------| | ||
| | `docs/development/benchmarking/nixlbench/index.md` | NIXLBench | Section index (overview + build) | | ||
| | `docs/development/benchmarking/nixlbench/usage.md` | NIXLBench Usage and Troubleshooting | Usage + troubleshooting | | ||
| | `docs/development/benchmarking/kvbench/index.md` | KVBench | Section index (overview + build) | | ||
| | `docs/development/benchmarking/kvbench/commands.md` | KVBench Commands and Examples | Commands, model config, examples | |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use one canonical benchmarking directory across the planning artifacts.
These planning files specify docs/development/benchmarking/..., while the supplied implementation uses docs/user-guide/benchmarking/....
.planning/phases/32-navigation-and-directory-setup/32-RESEARCH.md#L47-L62: resolve the directory discrepancy in favor of the actualdocs/user-guide/benchmarking/tree..planning/phases/35-kvbench-overview-and-build/35-RESEARCH.md#L9-L13: update the phase output paths and related navigation examples..planning/phases/35-kvbench-overview-and-build/35-01-PLAN.md#L7-L10: updatefiles_modifiedand all downstream references consistently.
📍 Affects 3 files
.planning/phases/32-navigation-and-directory-setup/32-RESEARCH.md#L47-L62(this comment).planning/phases/35-kvbench-overview-and-build/35-RESEARCH.md#L9-L13.planning/phases/35-kvbench-overview-and-build/35-01-PLAN.md#L7-L10
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/32-navigation-and-directory-setup/32-RESEARCH.md around
lines 47 - 62, Use docs/user-guide/benchmarking/ as the canonical directory
throughout the planning artifacts. In
.planning/phases/32-navigation-and-directory-setup/32-RESEARCH.md, revise the
directory discrepancy resolution and stub-file paths; update
.planning/phases/35-kvbench-overview-and-build/35-RESEARCH.md paths and
navigation examples; and update
.planning/phases/35-kvbench-overview-and-build/35-01-PLAN.md files_modified and
all downstream references consistently.
Comment on lines
+7
to
+10
| files_modified: | ||
| - docs/index.yml | ||
| - docs/development/benchmarking/nixlbench/index.md | ||
| - docs/development/benchmarking/nixlbench/build.md |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Use one canonical NIXLBench path throughout the planning documents.
The planning files prescribe inconsistent path families while the PR’s actual pages are under docs/user-guide/benchmarking/nixlbench.
.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md#L7-L10: update the modified-file paths and corresponding navigation paths..planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md#L107-L124: replace thedevelopment/benchmarkingnavigation example..planning/research/PITFALLS.md#L135-L145: update the recommended navigation template to the canonical layout.
📍 Affects 3 files
.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md#L7-L10(this comment).planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md#L107-L124.planning/research/PITFALLS.md#L135-L145
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md around lines
7 - 10, Use docs/user-guide/benchmarking/nixlbench as the canonical NIXLBench
path throughout the planning documentation. In
.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md lines 7-10,
update modified-file and navigation paths; in
.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md lines 107-124,
replace the development/benchmarking navigation example; and in
.planning/research/PITFALLS.md lines 135-145, update the recommended navigation
template.
Comment on lines
+194
to
+205
| | Option | Description | Default | | ||
| |--------|-------------|---------| | ||
| | `nixl_path` | Path to NIXL installation | `/usr/local` | | ||
| | `buildtype` | Build type: `debug`, `release`, `debugoptimized` | `release` | | ||
| | `prefix` | Installation prefix | `/usr/local` | | ||
| | `etcd_inc_path` | Path to etcd C++ client headers | `""` | | ||
| | `etcd_lib_path` | Path to etcd C++ client library | `""` | | ||
|
|
||
| - Post-install environment setup: | ||
| ```bash | ||
| export PATH=/usr/local/nixlbench/bin:$PATH | ||
| export LD_LIBRARY_PATH=/usr/local/nixlbench/lib:$LD_LIBRARY_PATH |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '175,220p' .planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md
printf '\n--- SEARCH ---\n'
rg -n "nixl_path|buildtype|prefix|meson setup|/usr/local/nixlbench|LD_LIBRARY_PATH|PATH" .planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.mdRepository: ai-dynamo/nixl
Length of output: 2565
🏁 Script executed:
sed -n '190,210p' .planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.mdRepository: ai-dynamo/nixl
Length of output: 915
Align the post-install paths with the install prefix. The setup command only sets nixl_path, so with the documented default prefix of /usr/local, these exports point at the wrong location. Either add -Dprefix=/usr/local/nixlbench or change the exports to /usr/local.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 203-203: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md around lines
194 - 205, Align the post-install environment setup with the documented
installation prefix: update the PATH and LD_LIBRARY_PATH exports to use the
prefix configured by the setup command, or explicitly configure that command
with prefix=/usr/local/nixlbench. Keep the nixl_path option and resulting
installation locations consistent.
Comment on lines
+95
to
+97
| - POSIX: `/docs/user-guide/backends/posix` | ||
| - HF3FS: `/docs/user-guide/backends/hf3fs` | ||
| - OBJ: `/docs/user-guide/backends/obj` |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the duplicated directory in both planned overview links.
.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md#L95-L97: change the links to./buildand./usage..planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md#L95-L97: apply the same sibling-relative links.
📍 Affects 2 files
.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md#L95-L97(this comment).planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md#L95-L97
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md around lines
95 - 97, Correct the duplicated directory in the planned overview links: update
the entries at .planning/phases/33-nixlbench-overview-and-build/33-RESEARCH.md
lines 95-97 and .planning/phases/33-nixlbench-overview-and-build/33-01-PLAN.md
lines 95-97 to use the sibling-relative links ./build and ./usage.
| # etcdWatchTimeout is configured at the C++ level; | ||
| # Python uses the default (5 seconds) unless set via the C++ bindings | ||
| agent = nixl_agent("my_agent", config) | ||
| ``` |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the reported Markdown/MDX lint errors.
Add blank lines around the affected fences and language identifiers to the untyped examples, including the raw etcd key-layout blocks.
Also applies to: 113-128, 161-161, 180-194, 223-223, 283-283, 319-319
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 90-90: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/etcd-metadata-exchange.md` at line 90, Fix the Markdown/MDX
lint errors in the untyped examples throughout the document, including the raw
etcd key-layout blocks. Add the required blank lines around each affected code
fence and its language identifier at the referenced sections, while preserving
the example content.
Source: Linters/SAST tools
Comment on lines
+95
to
+107
| NIXL stores metadata in etcd using a structured key hierarchy. Each agent's metadata is stored under a key composed of the namespace, agent name, and metadata type. | ||
|
|
||
| **Key format:** `{namespace}/{agent_name}/{metadata_type}` | ||
|
|
||
| The components are: | ||
|
|
||
| | Component | Source | Example | | ||
| |-----------|--------|---------| | ||
| | `namespace` | `NIXL_ETCD_NAMESPACE` env var (default `/nixl/agents/`) | `/nixl/agents/` | | ||
| | `agent_name` | The agent's unique name, set at construction | `agent_a` | | ||
| | `metadata_type` | Metadata label (default `"metadata"`) | `metadata` | | ||
|
|
||
| The default metadata label is `"metadata"` (the `default_metadata_label` constant). This means a default key for an agent named `agent_a` would be `/nixl/agents/agent_a/metadata`. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Define namespace slash normalization explicitly.
The format {namespace}/{agent_name}/{metadata_type} combined with namespaces ending in / produces // if concatenated literally, while the examples show a single /. Either remove the trailing slash from namespace values or document normalized concatenation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/etcd-metadata-exchange.md` around lines 95 - 107, Clarify the
key-format documentation by explicitly defining namespace slash normalization:
state that namespace values have their trailing slash removed before
concatenation, or document that components are joined with normalized
separators. Ensure the rule matches the single-slash examples and the default
NIXL_ETCD_NAMESPACE value.
Comment on lines
+175
to
+183
| ```python title="Python" | ||
| # Fetch a remote agent's metadata from ETCD | ||
| # (no IP/port arguments = ETCD mode) | ||
| agent.fetch_remote_metadata("remote_agent_name") | ||
|
|
||
| # Verify the metadata is loaded | ||
| while not agent.check_remote_metadata("remote_agent_name"): | ||
| pass | ||
| ``` |
Contributor
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Bound and yield the metadata polling loop.
while ...: pass busy-spins one CPU and can run forever if metadata is invalidated or the fetch fails. Prefer checking the fetch result directly, or add a deadline and a short sleep between polls.
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 180-180: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 183-183: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 183-183: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user-guide/etcd-metadata-exchange.md` around lines 175 - 183, Update the
metadata polling example around fetch_remote_metadata and check_remote_metadata
to avoid an unbounded busy-spin: use the fetch result directly if it indicates
completion, or add a clear deadline with a short sleep between checks and
explicit handling when the deadline is exceeded.
| .bd-footer__inner { padding: 0 1.5rem; } | ||
| .footer-items__start { gap: 1rem; } | ||
| .footer-links { flex-direction: row; gap: 0.5rem 0.75rem; } | ||
| .footer-links a { white-space: normal; word-break: break-word; } |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Resolve the reported Stylelint errors.
Replace deprecated wrapping properties and add the required separation between custom and standard declarations.
Proposed fix
- .footer-links a { white-space: normal; word-break: break-word; }
+ .footer-links a { white-space: normal; overflow-wrap: anywhere; }
.fig-caption {
--callout-border: transparent !important;
--callout-icon-color: var(--grayscale-a8) !important;
+
background-color: var(--nv-light-grey-1) !important;
.fern-button.outlined.normal {
background-color: transparent;
--tw-ring-color: transparent;
+
color: var(--nv-color-black);
- word-wrap: break-word;
+ overflow-wrap: break-word;Also applies to: 484-484, 569-569, 758-758
🧰 Tools
🪛 Stylelint (17.14.0)
[error] 408-408: Deprecated keyword "break-word" for property "word-break" (declaration-property-value-keyword-no-deprecated)
(declaration-property-value-keyword-no-deprecated)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@fern/main.css` at line 408, Update the footer link rules and the other
matching declarations in main.css to replace deprecated text-wrapping properties
with their current equivalents, and add the required blank line separating
custom properties from standard declarations. Apply the same Stylelint-compliant
changes at all reported occurrences while preserving the existing wrapping
behavior.
Source: Linters/SAST tools
| @@ -0,0 +1,5 @@ | |||
| | Variable | Type | Default | Description | | |||
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Add the repository-standard SPDX header.
Both copyright checks fail because this new MDX file has no copyright/license header. Copy the standard header format from another documentation snippet.
🧰 Tools
🪛 GitHub Actions: Copyright Checks / 0_copyright-checks.txt
[error] 1-1: SPDX header check: missing or incorrect copyright line.
🪛 GitHub Actions: Copyright Checks / copyright-checks
[error] 1-1: SPDX header check failed: missing or incorrect copyright line
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@fern/snippets/env-vars-libfabric.mdx` at line 1, Add the repository-standard
SPDX copyright and license header at the beginning of the MDX documentation
file, matching the format used by existing documentation snippets. Keep the
variable table unchanged.
Source: Pipeline failures
Comment on lines
+91
to
+102
| <verify>grep -c 'section: Benchmarking' docs/index.yml && grep -c 'section: NIXLBench' docs/index.yml && grep -c 'section: KVBench' docs/index.yml</verify> | ||
| <acceptance_criteria> | ||
| - docs/index.yml contains "section: Benchmarking" exactly once | ||
| - docs/index.yml contains "section: NIXLBench" exactly once | ||
| - docs/index.yml contains "section: KVBench" exactly once | ||
| - docs/index.yml contains "path: development/benchmarking/nixlbench/index.md" | ||
| - docs/index.yml contains "path: development/benchmarking/nixlbench/usage.md" | ||
| - docs/index.yml contains "path: development/benchmarking/kvbench/index.md" | ||
| - docs/index.yml contains "path: development/benchmarking/kvbench/commands.md" | ||
| - The Benchmarking section appears after "Building a Backend Plugin" and before the Examples section | ||
| - NIXLBench and KVBench sections each have "collapsed: open-by-default" | ||
| - The Benchmarking section does NOT have a "path:" attribute (no landing page) |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win
Make the navigation verification assert structure, not just counts.
The current grep -c checks do not fail on duplicate matches and cannot validate nesting, ordering, YAML validity, or the absence of a parent path: attribute. Add exact-count assertions plus a YAML/Fern parse check.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.planning/phases/32-navigation-and-directory-setup/32-01-PLAN.md around
lines 91 - 102, The verification for the Benchmarking navigation in the plan
must validate structure rather than only substring counts. Update the <verify>
command to assert each required section/path exactly once, parse docs/index.yml
with the repository’s available YAML/Fern tooling, and check nesting, ordering,
collapsed settings, and that the Benchmarking parent lacks a path attribute.
Comment on lines
+101
to
+107
| ### Fern MDX Patterns (established in Phase 33) | ||
|
|
||
| - **Frontmatter:** `title:` + `description:` on every page [VERIFIED: existing docs] | ||
| - **Callouts:** `<Warning>` for critical warnings, `<Note>` for supplementary info, `<Tip>` for helpful hints [VERIFIED: docs/api-reference/*.md, docs/user-guide/etcd-metadata-exchange.md] | ||
| - **Inline links:** Fern path format `/docs/user-guide/backends/ucx` (not relative paths) [VERIFIED: docs/development/benchmarking/nixlbench/index.md] | ||
| - **Code blocks:** Standard triple-backtick with language identifier [VERIFIED: existing docs] | ||
| - **Backend linking convention (Phase 33 D-09):** First mention of each backend name per page gets an inline link to its User Guide page [VERIFIED: index.md] |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Correct the obsolete NIXLBench documentation paths.
These references use docs/development/benchmarking/nixlbench, while the supplied stack places the pages under docs/user-guide/benchmarking/nixlbench. Update the source references, stub path, and validation commands; otherwise implementation and checks will target the wrong location.
Also applies to: 211-211, 293-296, 324-325
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-RESEARCH.md
around lines 101 - 107, Update all obsolete NIXLBench path references in this
research document from docs/development/benchmarking/nixlbench to
docs/user-guide/benchmarking/nixlbench, including source references, stub paths,
and validation commands. Ensure every affected occurrence, including the
sections around the cited lines, targets the supplied User Guide location.
Comment on lines
+109
to
+127
| ### Backend Link Map | ||
|
|
||
| All links verified against filesystem at `docs/user-guide/backends/`: | ||
|
|
||
| | Backend Name in Prose | Link Target | | ||
| |----------------------|-------------| | ||
| | UCX | `/docs/user-guide/backends/ucx` | | ||
| | GPUDirect Storage (GDS) | `/docs/user-guide/backends/gds` | | ||
| | GPUDirect Storage MT (GDS_MT) | `/docs/user-guide/backends/gds-mt` | | ||
| | POSIX | `/docs/user-guide/backends/posix` | | ||
| | DOCA GPUNetIO | `/docs/user-guide/backends/gpunetio` | | ||
| | Mooncake | `/docs/user-guide/backends/mooncake` | | ||
| | Libfabric | `/docs/user-guide/backends/libfabric` | | ||
| | HF3FS | `/docs/user-guide/backends/hf3fs` | | ||
| | OBJ | `/docs/user-guide/backends/obj` | | ||
| | Azure Blob | `/docs/user-guide/backends/azure-blob` | | ||
| | GUSLI | `/docs/user-guide/backends/gusli` | | ||
|
|
||
| [VERIFIED: `ls docs/user-guide/backends/` confirms all 12 files exist] |
Contributor
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Add the missing UCCL backend to the link map.
The document claims that all 12 backend pages are covered, but the map lists only 11 and omits docs/user-guide/backends/uccl.md. This can cause the implementation to violate NB-06/D-11 for UCCL. Add the missing row and reconcile the backend list/count.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-RESEARCH.md
around lines 109 - 127, Update the “Backend Link Map” to add UCCL with the
`/docs/user-guide/backends/uccl` target, and reconcile the verification note and
backend count so they accurately reflect all 12 backend pages.
Comment on lines
+213
to
+235
| ### Communication Pattern Example Structure | ||
|
|
||
| ```markdown | ||
| ### Pairwise | ||
|
|
||
| Pairwise transfers data between matched pairs of initiators and targets. This is the default scheme. | ||
|
|
||
| On host 1 (initiator): | ||
|
|
||
| ```bash | ||
| nixlbench --etcd_endpoints http://etcd-server:2379 --backend UCX \ | ||
| --initiator_seg_type VRAM --target_seg_type VRAM --scheme pairwise | ||
| ``` | ||
|
|
||
| On host 2 (target): | ||
|
|
||
| ```bash | ||
| nixlbench --etcd_endpoints http://etcd-server:2379 --backend UCX \ | ||
| --initiator_seg_type VRAM --target_seg_type VRAM --scheme pairwise | ||
| ``` | ||
| ``` | ||
|
|
||
| Source: Derived from README lines 596-603 and CLI flag `--scheme` at line 447 [VERIFIED: README] |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Fix the nested Markdown fences in the examples.
The outer ```markdown blocks contain inner triple-backtick fences, so Markdown will close the outer block at the first inner fence and render the examples incorrectly. Use four backticks for the outer fences (or indent the inner examples).
Also applies to: 237-257
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)
[warning] 232-232: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 233-233: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 233-233: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-RESEARCH.md
around lines 213 - 235, Update the outer Markdown fences in the communication
pattern examples around “Pairwise” and the additionally affected section to use
four backticks, preserving the inner triple-backtick bash fences and all example
content.
Source: Linters/SAST tools
Comment on lines
+280
to
+304
| ## Validation Architecture | ||
|
|
||
| ### Test Framework | ||
| | Property | Value | | ||
| |----------|-------| | ||
| | Framework | Fern docs build check | | ||
| | Config file | `fern/fern.config.json` | | ||
| | Quick run command | `cd fern && fern check` | | ||
| | Full suite command | `cd fern && fern check` | | ||
|
|
||
| ### Phase Requirements to Test Map | ||
| | Req ID | Behavior | Test Type | Automated Command | File Exists? | | ||
| |--------|----------|-----------|-------------------|-------------| | ||
| | NB-03 | Usage guide covers workers, ETCD, patterns, output | manual review + fern check | `cd fern && fern check` | stub exists at `docs/development/benchmarking/nixlbench/usage.md` | | ||
| | NB-04 | Troubleshooting covers 4 failure modes | manual review | grep for section headers in usage.md | stub exists | | ||
| | NB-05 | `<Warning>` callout for 60s barrier + ETCD link | manual review + fern check | grep for `<Warning>` and `/docs/user-guide/etcd-metadata-exchange` in usage.md | stub exists | | ||
| | NB-06 | Backend names link to User Guide pages | manual review | grep for backend link patterns in usage.md | stub exists | | ||
|
|
||
| ### Sampling Rate | ||
| - **Per task commit:** `cd fern && fern check` | ||
| - **Per wave merge:** `cd fern && fern check` + manual link verification | ||
| - **Phase gate:** `fern check` green + all 4 requirement checks pass | ||
|
|
||
| ### Wave 0 Gaps | ||
| None -- existing test infrastructure (fern check) covers all phase requirements. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Do not claim that fern check covers semantic requirements.
The validation table itself requires manual review and content-specific checks for NB-03 through NB-06, but “Wave 0 Gaps: None” says the existing infrastructure covers all requirements. Add executable content checks or explicitly retain these manual gates in the phase-completion criteria.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.planning/phases/34-nixlbench-usage-troubleshooting-and-cross-references/34-RESEARCH.md
around lines 280 - 304, Update the “Wave 0 Gaps” and phase-gate validation
language in the “Validation Architecture” section so it does not claim fern
check covers semantic requirements. Explicitly retain manual review and
content-specific checks for NB-03 through NB-06, or add executable checks for
those requirements, and ensure the phase-completion criteria require those
checks alongside fern check.
Comment on lines
+59
to
+65
| | Behavior | Command | Result | Status | | ||
| |----------|---------|--------|--------| | ||
| | fern check passes | `cd fern && fern check` | 0 errors, 1 warning (pre-existing) | PASS | | ||
| | No plugin in prose | `grep -rn '\bplugin\b' docs/user-guide/benchmarking/` | Zero matches | PASS | | ||
| | No ETCD in prose | `grep -rn '\bETCD\b' ... \| grep -v backtick/CLI` | Zero prose matches (2 CLI table values correct) | PASS | | ||
| | NIXLBench uses underscores | `grep 'etcd.endpoints' nixlbench/` | All 8 use `--etcd_endpoints` | PASS | | ||
| | KVBench uses hyphens | `grep 'etcd.endpoints' kvbench/` | All 8 use `--etcd-endpoints` | PASS | |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Make the CLI flag verification exact.
grep 'etcd.endpoints' treats . as a wildcard, so it matches both --etcd_endpoints and --etcd-endpoints. Use fixed-string or escaped patterns and assert that the opposite spelling is absent.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
@.planning/phases/37-terminology-normalization-and-quality-audit/37-VERIFICATION.md
around lines 59 - 65, Update the NIXLBench and KVBench verification commands in
the “NIXLBench uses underscores” and “KVBench uses hyphens” rows to use
fixed-string or escaped matching for the exact flag spelling, and add checks
asserting the opposite spelling is absent. Preserve the existing expected counts
and PASS criteria.
Comment on lines
+1
to
+2
| # NIXL Descriptor Class Hierarchy — Dark Mode | ||
| # Render: d2 --theme 200 --pad 20 docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2 docs/figures/data-flow/nixl_desc_hierarchy_dark.svg |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== File list =="
git ls-files docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2 docs/diagrams/data-flow/nixl_flow_01_init_light.d2
echo
echo "== Contents with line numbers =="
for f in docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2 docs/diagrams/data-flow/nixl_flow_01_init_light.d2; do
echo "--- $f ---"
cat -n "$f"
done
echo
echo "== Search for SPDX headers in repository D2/docs files =="
rg -n --glob '*.d2' --glob '*.md' --glob '*.txt' --glob '*.yaml' --glob '*.yml' 'SPDX-License-Identifier|Copyright' .
echo
echo "== Search for copyright-check config/mentions =="
rg -n 'copyright-check|SPDX-License-Identifier' .Repository: ai-dynamo/nixl
Length of output: 50373
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== SPDX headers in D2 files =="
rg -n --glob '*.d2' '^# SPDX-' . || true
echo
echo "== D2 files with copyright/license text =="
rg -n --glob '*.d2' 'Copyright|SPDX-License-Identifier|SPDX-FileCopyrightText' . || true
echo
echo "== Reuse / copyright config =="
git ls-files .reuse* .github/workflows/* scripts/* | sed -n '1,200p'
echo "--- .reuse files ---"
fd -H -t f '.*reuse.*|reuse' . | sed -n '1,50p'
echo "--- workflow mentions ---"
rg -n --glob '.github/workflows/**' 'reuse|copyright|SPDX|license' . || true
echo "--- repo config mentions ---"
rg -n --glob '.*' 'reuse|copyright|SPDX|license' .github .reuse* scripts . || trueRepository: ai-dynamo/nixl
Length of output: 1252
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== copyright-check.sh =="
cat -n .github/workflows/copyright-check.sh
echo
echo "== copyright-checks.yml =="
cat -n .github/workflows/copyright-checks.yml
echo
echo "== Any diagram examples with SPDX-style headers =="
rg -n --glob 'docs/**/*.d2' --glob 'docs/**/*.md' --glob 'benchmark/**/*.yaml' '^# SPDX-FileCopyrightText:|^# SPDX-License-Identifier:|^SPDX-FileCopyrightText:|^SPDX-License-Identifier:' .Repository: ai-dynamo/nixl
Length of output: 11093
Add the SPDX header to both D2 diagrams. Both files are covered by copyright-check.sh and currently miss the repository-standard SPDX header (SPDX-FileCopyrightText + SPDX-License-Identifier: Apache-2.0).
docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2docs/diagrams/data-flow/nixl_flow_01_init_light.d2
🧰 Tools
🪛 GitHub Actions: Copyright Checks / 0_copyright-checks.txt
[error] 1-1: SPDX header check: missing or incorrect copyright line.
🪛 GitHub Actions: Copyright Checks / copyright-checks
[error] 1-1: SPDX header check failed: missing or incorrect copyright line
📍 Affects 2 files
docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2#L1-L2(this comment)docs/diagrams/data-flow/nixl_flow_01_init_light.d2#L1-L3
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2` around lines 1 - 2, Add
the repository-standard SPDX header containing SPDX-FileCopyrightText and
SPDX-License-Identifier: Apache-2.0 to both
docs/diagrams/data-flow/nixl_desc_hierarchy_dark.d2 (lines 1-2) and
docs/diagrams/data-flow/nixl_flow_01_init_light.d2 (lines 1-3), preserving each
diagram’s existing content after the header.
Source: Pipeline failures
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preview URL (NVIDIA network only): http://10.237.219.64:3001/nixl
Comprehensive documentation for the NVIDIA Inference Xfer Library (NIXL):
Most of the work done by @kahalon . MR was open on the internal gitlab https://gitlab-master.nvidia.com/omrik/nixl/-/merge_requests/2
I have adressed in follow up commits (see commit history) the MR comments in gitlab, added the NIXL northbound specification and, improved the southbound API spec.
Summary by CodeRabbit
New Features
Documentation