From 6916a3de28df066cbb2e4f3b36b03bed73397bd0 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Tue, 10 Nov 2026 05:30:16 -0400 Subject: [PATCH 1/2] tools: list a pack's components, including the sibling vision directories (Refs #1503) Qwen3.5_4B/9B are not one flat pack: the root holds the text component and the vision graph ships as a sibling directory, in one of two forms -- compiled (dd_metastate_Llm_Vision_Vision_node_conv3d.fconst) in partitioned/, or ONNX (vision.onnx + .onnx.data + vision_strategy.yaml) in partitioned_patch1_sdgemm_leftover/. The engine has no notion of these directories yet, so a loader that reads only the root runs text-only and nothing says so. This makes the discovery rule checkable before the loader learns it: a directory is a component when it holds a compiled metastate set or an ONNX graph, the pack root is always 'text', and variant selection stays the caller's decision -- the tool lists every component with its form rather than picking one. Verified on the real pack (~/scratch-packs/qwen35_4b: text compiled 1872.1 MiB, partitioned compiled 360.1 MiB, patch1 onnx 84.7 MiB) and by --selftest, which needs no pack: three components across both forms, a directory with no graph ignored, an empty directory refused. Refs #1503 --- tools/npu_pack_components.py | 130 +++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100755 tools/npu_pack_components.py diff --git a/tools/npu_pack_components.py b/tools/npu_pack_components.py new file mode 100755 index 000000000..a207267a5 --- /dev/null +++ b/tools/npu_pack_components.py @@ -0,0 +1,130 @@ +#!/usr/bin/env python3 +# Copyright 2026 bong-water-water-bong +# SPDX-License-Identifier: Apache-2.0 +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +"""List the components of a Ryzen AI OGA pack, including the sibling-directory ones. + +A partitioned pack is not one flat component: the pack root holds the *text* component +(`text.bin`, `dd_metastate_Llm_Token_*`, `cache/`) and a vision component ships as a +sibling directory (`partitioned/`, `partitioned_patch1_sdgemm_leftover/`, `vit_*`), each a +complete component set of its own. The engine has no notion of these directories yet, so +this tool exists to make the rule checkable on the real files before the loader learns it +(engine #1503, plan W4). + +Discovery rule: a directory is a component when it holds a runnable description of one graph - +either compiled metastate (`dd_metastate_*.fconst`) or an ONNX graph (`*.onnx`, counting the +`*.onnx.data` sidecar). Both forms occur in the same pack: on `Qwen3.5_4B_rai_1.9.0_npu`, +`partitioned/` is the compiled vision component (`Llm_Vision_Vision_node_conv3d`) while +`partitioned_patch1_sdgemm_leftover/` is the same node as `vision.onnx` + `.onnx.data` + +`vision_strategy.yaml`. The pack root is always the `text` component. No manifest is invented +where the pack has none, and variant selection stays the caller's decision: this tool prints +every component, with its form, rather than silently picking one. +""" + +import argparse +import os +import sys + + +def components(root): + """(name, path, files, total_bytes, form) for the root and every sibling component.""" + out = [] + for name, path in [("text", root)] + sorted( + (entry, os.path.join(root, entry)) + for entry in os.listdir(root) + if os.path.isdir(os.path.join(root, entry)) + ): + entries = sorted(os.listdir(path)) + fconsts = [f for f in entries if f.startswith("dd_metastate_") and f.endswith(".fconst")] + onnx = [f for f in entries if f.endswith(".onnx") or f.endswith(".onnx.data")] + if not fconsts and not onnx: + continue + form = "compiled" if fconsts else "onnx" + files = fconsts or onnx + total = sum(os.path.getsize(os.path.join(path, f)) for f in files) + out.append((name, path, files, total, form)) + return out + + +def selftest(): + """Known-answer check on a synthetic layout: three components, both forms, plus the negative control.""" + import tempfile + + ok = True + with tempfile.TemporaryDirectory() as tmp: + # text (compiled) at the root, a compiled vision sibling, an ONNX vision sibling, and a decoy dir with no graph. + for d, names in ((tmp, ["dd_metastate_Llm_Token_x.fconst"]), + (os.path.join(tmp, "partitioned"), ["dd_metastate_Llm_Vision_Y.fconst"]), + (os.path.join(tmp, "partitioned_patch1_x"), ["vision.onnx", "vision.onnx.data"]), + (os.path.join(tmp, "decoy"), ["readme.txt"])): + os.makedirs(d, exist_ok=True) + for n in names: + with open(os.path.join(d, n), "wb") as f: + f.write(b"x" * 16) + got = {n: m for n, _p, _f, _b, m in components(tmp)} + want = {"text": "compiled", "partitioned": "compiled", "partitioned_patch1_x": "onnx"} + if got != want: + print(f"FAIL discovery: got {got} want {want}"); ok = False + if "decoy" in got: + print("FAIL discovery: a directory with no graph was reported as a component"); ok = False + # negative control: an empty directory has no components at all. + empty = os.path.join(tmp, "empty") + os.makedirs(empty, exist_ok=True) + if components(empty): + print("FAIL control: components found in an empty directory"); ok = False + print("selftest: " + ("PASS (3 components, both forms, decoy ignored, empty refused)" if ok else "FAIL")) + return 0 if ok else 1 + + +def main(): + ap = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + ap.add_argument("pack", nargs="?", help="pack directory (omit with --selftest)") + ap.add_argument("--json", action="store_true", help="machine-readable output") + ap.add_argument("--selftest", action="store_true", help="build a synthetic pack layout and check the rule") + args = ap.parse_args() + + if args.selftest: + return selftest() + if not args.pack: + print("pack directory required (or --selftest)", file=sys.stderr) + return 2 + + if not os.path.isdir(args.pack): + print(f"not a directory: {args.pack}", file=sys.stderr) + return 2 + comps = components(args.pack) + if not comps: + print("no components found (no dd_metastate_*.fconst and no *.onnx in the root or a sibling directory)", file=sys.stderr) + return 1 + + if args.json: + import json + + print(json.dumps([{"name": n, "dir": os.path.basename(p), "form": m, "files": f, "bytes": b} for n, p, f, b, m in comps], indent=2)) + return 0 + + print(f"pack: {args.pack}") + for name, path, files, total, form in comps: + print(f" {name:<8} {os.path.basename(path) or '.':<34} {form:<8} {len(files):>2} file {total / 2**20:>9.1f} MiB") + for f in files: + print(f" {f}") + if len(comps) > 1: + # Two components with the same role are variants: the caller must choose, never a glob order. + print(f" note: {len(comps)} components; the root is 'text' and the rest are siblings - " + f"a sibling whose role matches another sibling is a VARIANT and must be selected explicitly") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) From a918eca0e858d8da808aa32cdc54fa3b8cf3fc6a Mon Sep 17 00:00:00 2001 From: bong-water-water-bong <277547417+bong-water-water-bong@users.noreply.github.com> Date: Tue, 10 Nov 2026 22:50:18 -0400 Subject: [PATCH 2/2] tests: register the pack-component selftest, so the rule is run and not just written (Refs #1503, #1911, #2018) Reviewing #2018/#1911 caught this PR in its own trap: tools/npu_pack_components.py declares --selftest and nothing ran it, which is exactly the pattern #1911 added a sweep for. Registered as ctest 'npu_pack_components' beside the existing tools/*.py --self-test precedent (device_holders). Pure python, no pack, no device, no network. --- CMakeLists.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index eac988ab6..63119a496 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -407,6 +407,13 @@ add_test(NAME release_check_hrx_init_reason COMMAND bash ${CMAKE_SOURCE_DIR}/tes # then two lanes each starting an HRX server outside the token within one half hour). The ancestry test is the # check; the two permanent services are exempt by name. --self-test drives the decision, no device needed. add_python_test(device_holders ${CMAKE_SOURCE_DIR}/tools/device_holders.py --self-test) +# engine#1911/#2018: a tools/*.py whose --selftest nothing runs is a comment, not a test. npu_pack_components.py +# lists the components of a partitioned 1.9 pack (root text + sibling vision in either form) and its rule is pinned by +# --selftest, which builds a synthetic layout: three components across both forms, a directory with no graph ignored, +# an empty directory refused. Pure python, no pack on disk, no device, no network. Registered with add_python_test, +# matching the migration this file has already made for device_holders: the helper satisfies engine#1864's ordering +# rule by construction, so a future reorder cannot turn this row into BAD_COMMAND. +add_python_test(npu_pack_components ${CMAKE_SOURCE_DIR}/tools/npu_pack_components.py --selftest) # engine #1668: the bench preflight must pin the load mode, because `-lm none` is +17.5 % prefill at -1.6 % decode for +604 MiB of # GTT. The script existed with a test that nothing ran; a test nobody runs is a comment, so the loader/flag assertions are registered # here (the test fakes the box, so it needs no device and no ticket).