munet-nn 0.3.1__tar.gz

munet_nn-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: native-and-vulkan-correctness
+on:
+  workflow_call:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  worker-cxx-standards:
+    name: Native worker (C++${{ matrix.standard }})
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        standard: [17, 20, 23]
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev libssl-dev
+      # cxx_std_17 is a minimum: newer compiler defaults can select C++20 or later.
+      - name: Configure standalone worker
+        run: >-
+          cmake -S . -B build-worker -DCMAKE_BUILD_TYPE=Release
+          -DMUNET_PYTHON=OFF -DMUNET_VULKAN=OFF -DMUNET_SWARM_NODE=ON
+          -DCMAKE_CXX_STANDARD=${{ matrix.standard }} -DCMAKE_CXX_STANDARD_REQUIRED=ON
+      - run: cmake --build build-worker --parallel 2
+      - run: ./build-worker/munet-node --version
+
+  correctness:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        backend: [cpu, vulkan]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: sudo apt-get update && sudo apt-get install -y libvulkan-dev mesa-vulkan-drivers glslang-tools vulkan-validationlayers libcurl4-openssl-dev libssl-dev
+      - run: python -m pip install cmake pybind11 pytest numpy onnx onnxruntime onnxscript scikit-build-core scipy Pillow
+      - run: python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+      - name: Fetch pinned RT-DETR reference for numerical tests
+        run: python examples/rtdetr/fetch_reference.py
+      - name: Build CPU only
+        if: matrix.backend == 'cpu'
+        run: python tools/build.py --cpu-only --cmake-arg=-DMUNET_SWARM_NODE=ON
+      - name: Build Vulkan
+        if: matrix.backend == 'vulkan'
+        run: python tools/build.py --cmake-arg=-DMUNET_SWARM_NODE=ON
+      - name: Select software Vulkan driver
+        if: matrix.backend == 'vulkan'
+        shell: python
+        run: |
+          import glob, os
+          paths = glob.glob('/usr/share/vulkan/icd.d/lvp_icd*.json')
+          assert paths, 'Mesa software Vulkan ICD is required'
+          with open(os.environ['GITHUB_ENV'], 'a') as f:
+              f.write('VK_ICD_FILENAMES=' + paths[0] + '\nMUNET_TEST_VULKAN=1\n')
+      - name: CPU tests
+        if: matrix.backend == 'cpu'
+        run: python tools/test.py --swarm tests examples/rtdetr/tests
+        env:
+          PYTHONPATH: python
+      # Model-level GPU coverage (including RT-DETR) lives in the zoo suite; examples/rtdetr/tests is the CPU gate.
+      - name: Vulkan numerical and synchronization validation
+        if: matrix.backend == 'vulkan'
+        run: python tools/test.py --vulkan-validation --swarm tests examples/zoo/tests
+        env:
+          PYTHONPATH: python
+      - name: Full default R50-vd training state advancement
+        if: matrix.backend == 'cpu'
+        run: python -m examples.rtdetr.validate_training --device cpu
+        env:
+          PYTHONPATH: python
+      - name: Save numerical and fault-recovery evidence
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: correctness-${{ matrix.backend }}
+          path: artifacts/validation/

munet_nn-0.3.1/.github/workflows/wheels.yml

@@ -0,0 +1,222 @@
+# Keep this path: the existing munet-nn PyPI trusted publisher is bound to it.
+name: Wheels
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*", "dev*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: wheels-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  version:
+    name: Validate package and release identity
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install packaging
+      - run: python tools/release_version.py
+
+  correctness:
+    needs: version
+    uses: ./.github/workflows/ci.yml
+
+  build_wheels:
+    name: Wheels (${{ matrix.arch }})
+    needs: version
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            arch: x86_64
+          - runner: ubuntu-24.04-arm
+            arch: aarch64
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build and exercise installed CPU/Vulkan wheels
+        uses: pypa/cibuildwheel@v4.2.1
+        env:
+          CIBW_ARCHS_LINUX: ${{ matrix.arch }}
+          CIBW_BEFORE_ALL_LINUX: dnf -y install vulkan-headers libcurl-devel openssl-devel
+          # A single runtime per Python/platform avoids colliding CPU/GPU filenames.
+          CIBW_ENVIRONMENT_LINUX: >-
+            CMAKE_ARGS="-DMUNET_VULKAN=ON -DMUNET_SWARM_NODE=ON -DMUNET_INSTALL_SDK=OFF"
+          # libvulkan is loaded lazily from the host. auditwheel repairs the native
+          # worker and extension, including their libcurl/OpenSSL dependencies.
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.arch }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  source:
+    name: Source distribution
+    needs: version
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install build twine
+      - run: python -m build --sdist
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: source-dist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  native:
+    name: Node, server and SDK (${{ matrix.arch }})
+    needs: build_wheels
+    runs-on: ${{ matrix.runner }}
+    container: quay.io/pypa/manylinux_2_28_${{ matrix.arch }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            arch: x86_64
+          - runner: ubuntu-24.04-arm
+            arch: aarch64
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: wheels-linux-${{ matrix.arch }}
+          path: wheelhouse
+      - name: Install packaging tools and the actual CPython 3.12 wheel
+        shell: bash
+        run: |
+          # The /opt/python manylinux interpreters are static wheel builders.
+          # Freezing needs the distribution Python's shared libpython instead.
+          dnf -y install vulkan-headers python3.12 python3.12-pip python3.12-devel
+          /usr/bin/python3.12 -m venv /tmp/munet-freeze
+          /tmp/munet-freeze/bin/python -m pip install cmake pyinstaller==6.22.2 packaging
+          /tmp/munet-freeze/bin/python -m pip install wheelhouse/*cp312-cp312-*.whl
+      - name: Freeze server, package native node and SDK, and exercise all three
+        shell: bash
+        run: |
+          /tmp/munet-freeze/bin/python tools/build_release.py --wheel wheelhouse/*cp312-cp312-*.whl
+      - uses: actions/upload-artifact@v4
+        with:
+          name: native-linux-${{ matrix.arch }}
+          path: release-dist/*
+          if-no-files-found: error
+
+  validate_wheels:
+    name: Validate all distributions
+    needs: [build_wheels, source, native, correctness]
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: incoming
+      - uses: actions/download-artifact@v4
+        with:
+          name: source-dist
+          path: incoming/source
+      - run: python -m pip install packaging twine
+      - run: python tools/validate_artifacts.py incoming
+      - name: Collect validated, uniquely named Python distributions
+        shell: python
+        run: |
+          from pathlib import Path
+          import shutil, subprocess, sys
+          target = Path('dist')
+          target.mkdir()
+          for p in Path('incoming').rglob('*'):
+              if p.is_file() and (p.name.endswith('.whl') or p.name.endswith('.tar.gz')):
+                  assert not (target / p.name).exists(), p.name
+                  shutil.copyfile(p, target / p.name)
+          subprocess.run([sys.executable, '-m', 'twine', 'check', *map(str, target.iterdir())], check=True)
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/*
+
+  publish_testpypi:
+    name: Publish dev wheels to TestPyPI
+    needs: validate_wheels
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/dev')
+    runs-on: ubuntu-24.04
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          repository-url: https://test.pypi.org/legacy/
+
+  publish:
+    name: Publish release wheels to PyPI
+    needs: validate_wheels
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  release:
+    name: Publish standalone downloads
+    needs: [validate_wheels, publish]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: native-linux-*
+          path: release-dist
+          merge-multiple: true
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-distributions
+          path: release-dist
+      - name: Detect prerelease version
+        id: version
+        shell: python
+        run: |
+          import os, re
+          tag = os.environ['GITHUB_REF_NAME']
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
+              f.write('prerelease=' + str(bool(re.search(r'(?:a|b|rc)\d', tag))).lower() + '\n')
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: release-dist/*
+          fail_on_unmatched_files: true
+          generate_release_notes: true
+          prerelease: ${{ steps.version.outputs.prerelease }}

munet_nn-0.3.1/.gitignore

@@ -0,0 +1,20 @@
+build*/
+artifacts/
+dist/
+*.so
+*.pyd
+*.pyc
+__pycache__/
+.pytest_cache/
+.venv/
+*.egg-info/
+
+release-dist/
+wheelhouse/
+incoming/
+*.spec
+python/bin/
+python/include/
+python/lib/
+python/munet/bin/
+.venv-cuda/

munet_nn-0.3.1/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 0.3.1
+
+First PyPI release since 0.1.2 (0.3.0 was tagged but not published to PyPI). It includes the 0.2
+rewrite (unreleased on PyPI), the Vulkan performance, quantization and import work, and full ONNX operator coverage
+(all 191 operators of opsets 13-21). Measurements are on an RTX 3060 (driver 615.78) unless stated; see
+[docs/perf](docs/perf/README.md) for methodology and full tables.
+
+### Upgrade notes
+
+- **Swarm protocol is `munet-swarm-13`.** Generated kernels changed, so owners and nodes must run the same release;
+  a node from another release refuses the job's artifacts and assignments (ABI check), and compiled shaders are
+  verified by hash.
+- **`from_onnx` merges layers by default** (`optimize=True`): BatchNorm folding, parallel-branch re-parameterization,
+  linear-chain collapse and sibling merging. Results are exact up to float32 rounding; `program.optimizations` lists
+  the rewrites and `optimize=False` restores the graph as exported. Layer names in int8 selections refer to the
+  merged graph.
+- **Integer ONNX model inputs and outputs are accepted.** Integer/bool inputs are converted to float32 on the way in
+  (values above 2^24 are rejected), and integer outputs are returned as numpy arrays of their declared type instead
+  of lazy results.
+- **`NonMaxSuppression` imports when its result is a model output**, returned as int64 `[num_selected, 3]` with padding
+  removed; graphs that consume the result inside the model are rejected.
+- **Weights behind resident packs live in host-visible memory.** Device memory holds each inference weight once
+  (fp16, int8 or int4). The first call after loading or `Parameter.assign` is 30-80 ms slower on large models.
+- `precision="mixed_safe"` keeps the explicit attention backward (about 2% slower than before this release).
+
+### 0.2 rewrite (previously unreleased on PyPI)
+
+- Greenfield C++/Python runtime: traced static graphs compiled to Vulkan compute (single command-buffer replay, arena
+  memory, hazard-based barriers) with a CPU reference executor; the `munet-nn` / `munet_nn` package identity is
+  retained.
+- Resilient training swarm (native worker, owner server, leases, journaled recovery), installable Linux wheels,
+  frozen server bundle and CMake SDK.
+- Native RT-DETR training, inference and model interchange as a standalone source example (`examples/rtdetr`).
+- Makefile for setup, builds and CPU/Vulkan test runs.
+
+### Performance (Vulkan)
+
+- Mixed precision (fp16 inputs, fp32 accumulation) on cooperative matrices with unrolled fragment loops: GEMM
+  4096^3 at 23.5 TFLOP/s (90% of the measured ceiling, cuBLAS parity), implicit-GEMM convolutions (tap-major),
+  epilogue fusion, producer and permute/slice inlining, two-stage reductions, fp16 activations, split-K.
+- Fused flash attention forward and backward (S/P/dP/dS never reach memory): transformer training step 1.54x PyTorch
+  eager (was 1.70x).
+- `precision="fp32"` tuned: implicit-GEMM fp32 convolutions and a register-prefetched fp32 GEMM (ResNet-50 209 ->
+  17.8 ms, RT-DETR R50 452 -> 38.9 ms; PyTorch fp32 16.8 / 35.3 ms).
+- Tiled transposes and radix-select top-k (33600-wide top-300: 1.7 -> 0.14 ms); dependency-level kernel scheduling
+  when it costs no memory (batch-1 transformer 0.191 -> 0.119 ms).
+- Opt-in autotuner (`compile(autotune=True)`, `from_onnx(autotune=True)`), pipeline cache, zero-copy feeds with
+  double-buffered input staging.
+- Against PyTorch eager on the same GPU: ResNet-50, ViT-S/16 and GPT at parity or better; RT-DETR R50 inference
+  0.68x; TensorRT remains 2.2-3.6x faster on CNN/ViT inference.
+
+### Quantization
+
+- int8 GEMM (W8A8, 16x16x32 int8 cooperative matrices, 54 TOP/s) and int8 implicit-GEMM convolutions
+  (channels-last int8 activations; 3x3 convolutions 1.4-2.8x faster than fp16).
+- Weight-only `w8`/`w4` that save memory and bandwidth: a streaming GEMV for up to 8 rows (batch 1: 2.3x / 4.0x faster
+  than fp16) and dequantizing cooperative-matrix tiles above that.
+- `mu.quantize` (w8a8, w8a8_dynamic, w8, w4; minmax/percentile/mse observers), ONNX QDQ/QLinear import and export.
+- `munet.quantization.calibrate_onnx` (MSE histogram calibration) and `from_onnx(int8=...)`.
+- `munet.quantization.autoquantize`: per-layer int8 selection from measured per-layer speed and a task metric within
+  a tolerance. On an RT-DETR-style 1280x1280 detector: 24 of 80 layers in int8, 23.67 -> 21.07 ms, mAP50
+  86.30 -> 85.90.
+
+### Import and coverage
+
+- ONNX: all 191 operators of opsets 13-21, machine-checked coverage table. New in this release: bitwise ops and BitShift, Det, ScatterElements/ScatterND, GatherND, MaxUnpool, MaxRoiPool, Col2Im, ReverseSequence, ReduceProd, AffineGrid, CenterCropPad, DeformConv, DFT, STFT, window functions, MelWeightMatrix, DynamicQuantizeLinear, RNN/GRU/LSTM (unrolled), TfIdfVectorizer, random operators (new samples every call), sequences and optionals (resolved at import), If/Loop/Scan/SequenceMap (branch selection or Where, unrolled loops), and string/bytes operators and Unique from constant inputs; shape-specialized programs for symbolic
+  dimensions; `from_onnx(precision=, autotune=, int8=, optimize=, profile=)`; graph nodes carry ONNX node names
+  (`describe()` attributes kernels to layers).
+- Weight-level layer merging (`munet.onnx_passes`): a RepVGG-style network in training form 4.28 -> 3.02 ms.
+- Model zoo (`examples/zoo`: ResNet-18/50, MobileNetV2, ViT, U-Net, GPT, BERT, DETR, YOLO, RT-DETR) with PyTorch
+  twins, mixed-precision accuracy and ONNX round trips. Model-level Vulkan tests live in the zoo suite;
+  `examples/rtdetr/tests` is the detector's CPU reference gate.
+- RoiAlign and fixed-size NMS (`nn.functional.nms` / `batched_nms`).

munet_nn-0.3.1/CMakeLists.txt

@@ -0,0 +1,71 @@
+cmake_minimum_required(VERSION 3.20)
+file(STRINGS "${CMAKE_CURRENT_SOURCE_DIR}/pyproject.toml" _munet_version_line REGEX "^version = ")
+string(REGEX REPLACE ".*\"([^\"]+)\".*" "\\1" MUNET_VERSION "${_munet_version_line}")
+string(REGEX MATCH "^[0-9]+\\.[0-9]+\\.[0-9]+" MUNET_ABI_VERSION "${MUNET_VERSION}")
+project(MuNet VERSION ${MUNET_ABI_VERSION} LANGUAGES CXX)
+include(GNUInstallDirs)
+option(MUNET_VULKAN "Build the Vulkan compute runtime" ON)
+option(MUNET_PYTHON "Build the Python interface" ON)
+option(MUNET_SWARM_NODE "Build the standalone Linux/POSIX swarm worker" OFF)
+option(MUNET_INSTALL_SDK "Install the C++ library, headers, and CMake package" ON)
+add_library(munet_core STATIC cpp/core.cpp cpp/matmul.cpp cpp/attention.cpp cpp/layout.cpp cpp/ops.cpp cpp/vulkan.cpp)
+file(GLOB MUNET_KERNELS CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/cpp/kernels/*.inc")
+set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${MUNET_KERNELS})
+set(MUNET_KERNEL_SOURCE "")
+foreach(kernel IN LISTS MUNET_KERNELS)
+  get_filename_component(kernel_name "${kernel}" NAME_WE)
+  file(READ "${kernel}" kernel_text)
+  string(APPEND MUNET_KERNEL_SOURCE "{\"${kernel_name}\", R\"kernel(${kernel_text})kernel\"},\n")
+endforeach()
+configure_file(cmake/kernel_sources.hpp.in kernel_sources.hpp @ONLY)
+target_include_directories(munet_core PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
+add_library(MuNet::core ALIAS munet_core)
+target_compile_features(munet_core PUBLIC cxx_std_17)
+target_include_directories(munet_core PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/cpp>
+  $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
+set_target_properties(munet_core PROPERTIES POSITION_INDEPENDENT_CODE ON EXPORT_NAME core)
+if(MUNET_VULKAN)
+  # CPU execution and owner startup must work without a Vulkan loader installed.
+  find_path(Vulkan_INCLUDE_DIR vulkan/vulkan.h HINTS "$ENV{VULKAN_SDK}/include" REQUIRED)
+  target_include_directories(munet_core PRIVATE ${Vulkan_INCLUDE_DIR})
+  target_link_libraries(munet_core PRIVATE ${CMAKE_DL_LIBS})
+  target_compile_definitions(munet_core PRIVATE MUNET_VULKAN=1)
+endif()
+if(MUNET_SWARM_NODE)
+  if(NOT UNIX)
+    message(FATAL_ERROR "The v1 swarm worker currently requires POSIX file locking and fsync")
+  endif()
+  find_package(CURL REQUIRED)
+  find_package(OpenSSL REQUIRED)
+  find_package(Threads REQUIRED)
+  add_executable(munet-node cpp/swarm/node.cpp)
+  target_include_directories(munet-node PRIVATE cpp/third_party)
+  target_link_libraries(munet-node PRIVATE munet_core CURL::libcurl OpenSSL::Crypto Threads::Threads)
+  target_compile_definitions(munet-node PRIVATE MUNET_VERSION="${MUNET_VERSION}")
+  if(SKBUILD)
+    install(TARGETS munet-node RUNTIME DESTINATION munet/bin)
+  else()
+    install(TARGETS munet-node RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+  endif()
+endif()
+if(MUNET_INSTALL_SDK)
+  include(CMakePackageConfigHelpers)
+  install(TARGETS munet_core EXPORT MuNetTargets ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+  install(FILES cpp/core.hpp DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/munet)
+  install(EXPORT MuNetTargets NAMESPACE MuNet:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MuNet)
+  configure_package_config_file(cmake/MuNetConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/MuNetConfig.cmake
+    INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MuNet)
+  write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/MuNetConfigVersion.cmake
+    VERSION ${PROJECT_VERSION} COMPATIBILITY SameMinorVersion)
+  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/MuNetConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/MuNetConfigVersion.cmake
+    DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/MuNet)
+endif()
+if(MUNET_PYTHON)
+  set(PYBIND11_FINDPYTHON ON)
+  find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+  find_package(pybind11 CONFIG REQUIRED)
+  pybind11_add_module(_native cpp/bindings.cpp)
+  target_link_libraries(_native PRIVATE munet_core)
+  install(TARGETS _native LIBRARY DESTINATION munet RUNTIME DESTINATION munet)
+endif()

munet_nn-0.3.1/Makefile

@@ -0,0 +1,95 @@
+.DEFAULT_GOAL := help
+# Native builds install into the same source tree; serialize multi-target invocations.
+.NOTPARALLEL:
+
+PYTHON ?= python3
+VENV ?= .venv
+VULKAN ?= 1
+BUILD_DIR ?= build/local
+CMAKE_ARGS ?=
+TORCH_INDEX_URL ?= https://download.pytorch.org/whl/cpu
+DEVICE ?= cpu
+
+VENV_PYTHON := $(abspath $(VENV))/bin/python
+RUN := env PYTHONPATH="$(CURDIR)/python" MUNET_SWARM_NODE="$(abspath $(BUILD_DIR))/munet-node" "$(VENV_PYTHON)"
+BUILD_FLAGS := --build-dir="$(BUILD_DIR)" --cmake-arg=-DMUNET_SWARM_NODE=ON --cmake-arg=-DMUNET_INSTALL_SDK=OFF
+ifeq ($(VULKAN),0)
+BUILD_FLAGS += --cpu-only
+endif
+ifeq ($(filter 0 1,$(VULKAN)),)
+$(error VULKAN must be 0 or 1)
+endif
+
+.PHONY: help setup deps build test-deps rtdetr-deps setup-rtdetr reference test test-vulkan test-rtdetr test-zoo smoke install clean
+
+help:
+	@printf '%s\n' \
+	  'make setup           Create .venv and build the library/node (no PyTorch or model downloads)' \
+	  'make setup VULKAN=0  Set up without Vulkan headers or a GPU driver' \
+	  'make build           Rebuild native code after edits (incremental)' \
+	  'make test            Install reference-test tools and run library CPU/swarm tests' \
+	  'make test-vulkan     CPU + Vulkan tests with API/synchronization validation (VULKAN=1)' \
+	  'make setup-rtdetr    Set up the optional RT-DETR example and image dependencies' \
+	  'make test-rtdetr     Run RT-DETR example acceptance tests (CPU reference; GPU coverage is in test-zoo)' \
+	  'make test-zoo        Run model-zoo parity/ONNX tests (VULKAN=1 adds Vulkan with validation)' \
+	  'make smoke           Run the small MLP training example (DEVICE=cpu or vulkan)' \
+	  'make install         Install library and node/server commands into the virtual environment' \
+	  'make clean           Clean native build outputs; keep dependencies, data and checkpoints' \
+	  '' \
+	  'Overrides: PYTHON, VENV, VULKAN=0|1, BUILD_DIR, CMAKE_ARGS, TORCH_INDEX_URL, DEVICE' \
+	  'Use the same overrides for later commands. See docs/install.md for system prerequisites.'
+
+$(VENV_PYTHON):
+	"$(PYTHON)" -m venv "$(VENV)"
+
+# Keep the development dependencies aligned with pyproject.toml and ci.yml.
+$(VENV)/.munet-deps: pyproject.toml Makefile | $(VENV_PYTHON)
+	"$(VENV_PYTHON)" -m pip install --upgrade pip
+	"$(VENV_PYTHON)" -m pip install 'cmake>=3.20' 'pybind11>=3.0' 'scikit-build-core>=0.10' 'numpy>=1.24' 'pytest>=8' 'onnx>=1.16'
+	touch "$@"
+
+$(VENV)/.munet-test-deps: pyproject.toml Makefile | deps
+	"$(VENV_PYTHON)" -m pip install 'onnxruntime>=1.18' 'onnxscript>=0.3' 'scipy>=1.10'
+	"$(VENV_PYTHON)" -m pip install 'torch>=2.6' torchvision --index-url "$(TORCH_INDEX_URL)"
+	touch "$@"
+
+$(VENV)/.munet-rtdetr-deps: examples/rtdetr/requirements.txt | deps
+	"$(VENV_PYTHON)" -m pip install -r examples/rtdetr/requirements.txt
+	touch "$@"
+
+deps: $(VENV)/.munet-deps
+test-deps: $(VENV)/.munet-test-deps
+rtdetr-deps: $(VENV)/.munet-rtdetr-deps
+
+setup: build
+setup-rtdetr: build rtdetr-deps
+
+build: deps
+	"$(VENV_PYTHON)" tools/build.py $(BUILD_FLAGS) $(CMAKE_ARGS)
+
+reference: $(VENV_PYTHON)
+	"$(VENV_PYTHON)" examples/rtdetr/fetch_reference.py
+
+test: build test-deps
+	MUNET_TEST_VULKAN=0 $(RUN) tools/test.py --swarm
+
+test-vulkan:
+	@test "$(VULKAN)" = 1 || { printf '%s\n' 'Use make test-vulkan VULKAN=1 to build and test the Vulkan runtime.'; exit 1; }
+	$(MAKE) build test-deps
+	$(RUN) tools/test.py --vulkan-validation --swarm
+
+test-rtdetr: build test-deps rtdetr-deps reference
+	MUNET_TEST_VULKAN=0 $(RUN) tools/test.py examples/rtdetr/tests
+
+test-zoo: build test-deps reference
+	$(if $(filter 1,$(VULKAN)),$(RUN) tools/test.py --vulkan-validation examples/zoo/tests,MUNET_TEST_VULKAN=0 $(RUN) tools/test.py examples/zoo/tests)
+
+smoke: build
+	$(RUN) examples/train_mlp.py --device "$(DEVICE)" --steps 20
+
+# Normal installation for scripts outside this checkout; rerun after source edits.
+install: deps
+	"$(VENV_PYTHON)" -m pip install --no-build-isolation --no-deps . -Ccmake.define.MUNET_VULKAN=$(if $(filter 0,$(VULKAN)),OFF,ON)
+
+clean:
+	@if test -f "$(BUILD_DIR)/CMakeCache.txt"; then "$(VENV_PYTHON)" -m cmake --build "$(BUILD_DIR)" --target clean; fi