Arm backend: Make Model Explorer dependencies optional (pytorch#22993)

### Summary

Related to pytorch#22314.

Default Arm setup installs Model Explorer adapters that require Python
below 3.13, even when visualization is unused. Make visualization opt-in
with `--enable-model-explorer` and install its complete dependency graph
in an isolated directory so its FlatBuffers requirements do not conflict
with the TOSA toolchain.

Update `run.sh` to request the optional dependencies during automatic
setup, validate only the selected adapter, and expose the isolated
packages only during visualization. Resolve Python from the active
environment and check its major/minor version instead of retaining an
absolute interpreter path. Document supported versions and reject
unsupported visualization configurations early.

The core toolchain versions remain unchanged. The existing `tosa-tools`
pin still prevents Python 3.14 installation and needs a separate
dependency upgrade. The PTE adapter also retains its upstream transitive
dependency on the VGF adapter; this change adds no separate VGF
requirement.

Authored with assistance from Codex.

### Test plan

On Python 3.12, installed the complete optional dependency graph into an
isolated directory. `pip check`, deep PTE/TOSA adapter imports, and the
Model Explorer CLI passed. Repeated validation after replacing the
virtual environment and moving the installed packages.

To repeat the isolated dependency checks from the repository root:

```bash
check_dir=$(mktemp -d)
python3.12 -m venv "$check_dir/venv"
"$check_dir/venv/bin/python" -m pip install \
  --ignore-installed --no-warn-conflicts \
  --target "$check_dir/packages" \
  -r backends/arm/requirements-arm-model-explorer.txt
PYTHONPATH="$check_dir/packages" "$check_dir/venv/bin/python" -m pip check
PYTHONPATH="$check_dir/packages" "$check_dir/venv/bin/python" -c \
  'import pte_adapter_model_explorer.main, tosa_adapter_model_explorer.main'
PYTHONPATH="$check_dir/packages" "$check_dir/venv/bin/python" \
  -m model_explorer --help
```

Passed 15 local shell behavior checks using a temporary harness with
stubbed setup/export: early rejection of unsupported Python versions,
sourced-shell behavior, automatic setup with and without visualization,
selected-adapter validation, Python minor-version mismatch, invalid
flags, and isolation from model export. This harness is not added to the
repository.

Shell syntax and whitespace checks passed:

```bash
bash -n examples/arm/setup.sh
bash -n examples/arm/run.sh
git diff --check HEAD^ HEAD
```

Lintrunner and the Arm pre-push checks also passed, including license
checks, documentation checks, VGF operator coverage, and public API
manifest validation. Full model export and FVP execution were not rerun
for this dependency-isolation change.


cc @digantdesai @freddan80 @per @zingo @oscarandersson8218 @mansnils
@Sebastian-Larsson @robell @rascani

Signed-off-by: Usamah Zaheer <usamah.zaheer@arm.com>

Author: usamahz

backends/arm/requirements-arm-ethos-u.txt

@@ -6,4 +6,3 @@
 # These dependencies need to match pyproject.toml
 
 ethos-u-vela == 5.1.0
-pte-adapter-model-explorer == 0.0.2

backends/arm/requirements-arm-model-explorer.txt

@@ -0,0 +1,13 @@
+# Copyright 2026 Arm Limited and/or its affiliates.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Model Explorer adapters currently require Python >=3.10,<3.13. These are
+# installed in an isolated target directory by examples/arm/setup.sh because
+# their FlatBuffers requirement conflicts with the TOSA toolchain.
+
+numpy >= 2.0, < 2.2
+ai-edge-model-explorer == 0.1.28
+pte-adapter-model-explorer == 0.0.2
+tosa-adapter-model-explorer == 0.1.0

backends/arm/requirements-arm-tosa.txt

@@ -7,7 +7,5 @@
 
 ml_dtypes == 0.5.1
 flatbuffers == 24.3.25
-tosa-adapter-model-explorer == 0.1.0
-ai-edge-model-explorer >= 0.1.16
 pytest-timeout == 2.4.0
 tosa-tools == 2026.5.0

examples/arm/README.md

@@ -42,6 +42,45 @@ Example to install the default Arm backend dependencies and add them to your cur
 source examples/arm/arm-scratch/setup_path.sh
 ```
 
+The Arm toolchain dependencies have their own Python constraints. In
+particular, the pinned `tosa-tools==2026.5.0` has no Python 3.14 distribution;
+making visualization optional does not remove that separate limitation.
+
+Model Explorer visualization is optional and currently supports Python
+3.10-3.12. Add `--enable-model-explorer` to install it and the TOSA/PTE adapters in
+an isolated directory, keeping their dependencies separate from the TOSA
+toolchain:
+
+```bash
+./examples/arm/setup.sh \
+  --i-agree-to-the-contained-eula \
+  --enable-model-explorer
+```
+
+Run visualization from an ExecuTorch environment on the same platform and
+Python major/minor version used for setup. The interpreter is resolved from
+the active environment, allowing a replacement environment or a moved
+scratch directory without retaining the original interpreter path.
+The PTE adapter currently also brings in the VGF adapter as a transitive
+dependency; `run.sh` exposes only TOSA/PTE visualization.
+
+Select the graph format explicitly when enabling Model Explorer. For example,
+to visualize the generated TOSA graph:
+
+```bash
+./examples/arm/run.sh \
+  --model_name=examples/arm/example_modules/add.py \
+  --target=ethos-u55-128 \
+  --build_only \
+  --model_explorer \
+  --visualize_tosa
+```
+
+Use `--visualize_pte` instead of `--visualize_tosa` to visualize the generated
+PTE and its delegated graphs.
+When `run.sh` automatically invokes setup on a fresh checkout,
+`--model_explorer` also enables installation of the visualization dependencies.
+
 ## run.sh
 
 `run.sh` is an end-to-end helper for building and executing an Arm backend

examples/arm/run.sh

@@ -46,6 +46,8 @@ toolchain="arm-none-eabi-gcc"
 select_ops_list="aten::_softmax.out"
 select_ops_list_overridden=false
 model_explorer=false
+model_explorer_dir=""
+model_explorer_pythonpath=""
 perf_overlay=false
 visualize_tosa=false
 visualize_pte=false
@@ -146,6 +148,26 @@ if [ "$perf_overlay" = true ] && [ "$visualize_tosa" != true ]; then
     exit 1
 fi
 
+if [[ "$model_explorer" != true && ("$visualize_tosa" = true || "$visualize_pte" = true) ]]; then
+    echo "Error: --visualize_tosa and --visualize_pte require --model_explorer" >&2
+    exit 1
+fi
+
+if [[ "$model_explorer" = true && "$visualize_tosa" = "$visualize_pte" ]]; then
+    echo "Error: --model_explorer requires exactly one of --visualize_tosa or --visualize_pte" >&2
+    exit 1
+fi
+
+if [[ "$perf_overlay" = true && "$visualize_tosa" != true ]]; then
+    echo "Error: --perf_overlay requires --visualize_tosa" >&2
+    exit 1
+fi
+
+if [[ "$perf_overlay" = true && ${target} != ethos-u* ]]; then
+    echo "Error: --perf_overlay requires an Ethos-U target" >&2
+    exit 1
+fi
+
 # Cortex-M backend is an operator-library, not a delegate; force-disable
 # --delegate when targeting cortex-m so users don't need --no_delegate.
 if [[ ${target} == cortex-m* ]]; then
@@ -598,8 +620,12 @@ EOF
 #######
 if ! check_setup; then
     if [ "$scratch_dir_set" = false ] ; then
+	setup_cmd=("${script_dir}/setup.sh")
+	if [[ "$model_explorer" = true ]]; then
+	    setup_cmd+=(--enable-model-explorer)
+	fi
 	# check setup failed, no scratchdir given as parameter. trying to run setup.sh
-	if ${script_dir}/setup.sh; then
+	if "${setup_cmd[@]}"; then
 	    # and recheck setup. If this fails exit.
 	    if ! check_setup; then
 		exit 1
@@ -611,6 +637,38 @@ if ! check_setup; then
     fi
 fi
 
+if [[ "$model_explorer" = true ]]; then
+    model_explorer_dir="${arm_scratch_dir}/model-explorer"
+    if [[ ! -f "${model_explorer_dir}/.python-version" ]]; then
+        echo "Error: Model Explorer dependencies not found at ${model_explorer_dir}." >&2
+        echo "Rerun setup.sh with --enable-model-explorer and a matching --root-dir." >&2
+        exit 1
+    fi
+
+    IFS= read -r model_explorer_python_version < "${model_explorer_dir}/.python-version"
+    if [[ "$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')" \
+          != "${model_explorer_python_version}" ]]; then
+        echo "Error: Model Explorer was installed for Python ${model_explorer_python_version}." >&2
+        echo "Activate a matching Python environment or rerun setup.sh with --enable-model-explorer." >&2
+        exit 1
+    fi
+
+    model_explorer_pythonpath="${model_explorer_dir}"
+    if [[ -n "${PYTHONPATH:-}" ]]; then
+        model_explorer_pythonpath="${model_explorer_pythonpath}:${PYTHONPATH}"
+    fi
+    model_explorer_adapter="tosa_adapter_model_explorer.main"
+    if [[ "$visualize_pte" = true ]]; then
+        model_explorer_adapter="pte_adapter_model_explorer.main"
+    fi
+    if ! PYTHONPATH="${model_explorer_pythonpath}" python3 -c \
+        'import importlib, sys; importlib.import_module(sys.argv[1])' "${model_explorer_adapter}"; then
+        echo "Error: The Model Explorer installation failed its import check." >&2
+        echo "Rerun setup.sh with --enable-model-explorer and a matching --root-dir." >&2
+        exit 1
+    fi
+fi
+
 cd "${et_root_dir}"
 
 bundleio_flag=""
@@ -676,6 +734,29 @@ configure_ethosu_scratch_if_requested() {
     "${cmake_cmd[@]}"
 }
 
+visualize_model() {
+    if [[ "$model_explorer" != true ]]; then
+        return
+    fi
+
+    local model_explorer_args=(--model_dir "${output_folder}")
+    if [[ "$visualize_tosa" = true ]]; then
+        model_explorer_args+=(--tosa)
+    else
+        model_explorer_args+=(--pte)
+    fi
+    if [[ "$perf_overlay" = true ]]; then
+        model_explorer_args+=(
+            --trace "${output_folder}/pmu_trace.gz"
+            --tables "${output_folder}/output/out_debug.xml"
+        )
+    fi
+
+    PYTHONPATH="${model_explorer_pythonpath}" \
+        python3 "${script_dir}/visualize.py" \
+        "${model_explorer_args[@]}"
+}
+
 if [[ -z "$model_name" ]]; then
     echo "[run.sh] WARNING: Built-in test models executed when --model_name is omitted are deprecated and will be removed after the ExecuTorch 1.2 release." >&2
     # the test models run, and whether to delegate
@@ -766,6 +847,7 @@ for i in "${!test_model[@]}"; do
 
     if [[ ${target} == *"TOSA"*  ]]; then
         echo "Build for ${target} skip generating a .elf and running it"
+        visualize_model
         continue
     elif [[ ${target} == cortex-m*  ]]; then
         # Cortex-M backend uses a semihosting executor_runner (built by
@@ -828,23 +910,7 @@ for i in "${!test_model[@]}"; do
         fi
     fi
 
-    if [ "$model_explorer" = true ]; then
-        perf_flags=""
-        if [ "$perf_overlay" = true ]; then
-            perf_flags+=" --trace ${output_folder}/pmu_trace.gz --tables ${output_folder}/output/out_debug.xml"
-        fi
-
-        visualization_file=""
-        if [ "$visualize_tosa" = true ]; then
-            visualization_file+=" --tosa"
-        fi
-        if [ "$visualize_pte" = true ]; then
-            visualization_file+=" --pte"
-        fi
-
-        me_flags="${visualization_file} ${perf_flags}"
-        python3 ${script_dir}/visualize.py --model_dir ${output_folder} ${me_flags}
-    fi
+    visualize_model
 done
 
 exit 0

examples/arm/setup.sh

@@ -30,6 +30,7 @@ enable_model_converter=0   # model-converter tool for VGF output
 enable_vgf_lib=0  # vgf reader - runtime backend dependency
 enable_emulation_layer=0  # Vulkan layer driver - emulates Vulkan ML extensions
 enable_vulkan_sdk=0  # Download and export Vulkan SDK required by emulation layer
+enable_model_explorer=0
 
 # Figure out if setup.sh was called or sourced and save it into "is_script_sourced"
 (return 0 2>/dev/null) && is_script_sourced=1 || is_script_sourced=0
@@ -55,6 +56,7 @@ OPTION_LIST=(
   "--enable-model-converter Enable MLSDK model converter setup"
   "--enable-vgf-lib Enable MLSDK vgf library setup"
   "--enable-emulation-layer Enable MLSDK Vulkan emulation layer"
+  "--enable-model-explorer Install optional Model Explorer visualization dependencies"
   "--disable-ethos-u-deps Do not setup what is needed for Ethos-U"
   "--enable-mlsdk-deps Setup what is needed for MLSDK"
   "--install-mlsdk-deps-with-pip (default) Use MLSDK PyPI packages"
@@ -144,6 +146,10 @@ function check_options() {
                 enable_vulkan_sdk=1
                 shift
                 ;;
+            --enable-model-explorer)
+                enable_model_explorer=1
+                shift
+                ;;
             --disable-ethos-u-deps)
                 enable_baremetal_toolchain=0
                 enable_fvps=0
@@ -234,6 +240,44 @@ function setup_cortex_m_tools() {
     pip install --no-dependencies -r $et_dir/backends/cortex_m/requirements-cortex-m.txt
 }
 
+function check_model_explorer_python() {
+    local py_version
+    py_version="$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
+    if ! python3 -c 'import sys; raise SystemExit(0 if (3, 10) <= sys.version_info < (3, 13) else 1)'; then
+        log_step "model-explorer" \
+            "Model Explorer adapters require Python 3.10-3.12; detected Python ${py_version}."
+        return 1
+    fi
+}
+
+function setup_model_explorer() {
+    check_model_explorer_python || return 1
+
+    local model_explorer_dir="${root_dir}/model-explorer"
+    local staging_dir
+    staging_dir="$(mktemp -d "${root_dir}/model-explorer.XXXXXX")"
+
+    log_step "model-explorer" "Installing optional visualization dependencies"
+    if ! python3 -m pip install --ignore-installed --no-warn-conflicts \
+        --target "${staging_dir}" \
+        -r "${et_dir}/backends/arm/requirements-arm-model-explorer.txt"; then
+        rm -rf "${staging_dir}"
+        return 1
+    fi
+    if ! PYTHONPATH="${staging_dir}" python3 -c \
+        'import pte_adapter_model_explorer.main, tosa_adapter_model_explorer.main' || \
+       ! PYTHONPATH="${staging_dir}" python3 -m model_explorer --help >/dev/null; then
+        log_step "model-explorer" "Installed packages failed validation"
+        rm -rf "${staging_dir}"
+        return 1
+    fi
+
+    python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' \
+        > "${staging_dir}/.python-version"
+    rm -rf "${model_explorer_dir}"
+    mv "${staging_dir}" "${model_explorer_dir}"
+}
+
 function warn_if_mlsdk_python_is_untested() {
     if [[ "${enable_model_converter}" -eq 0 && \
           "${enable_vgf_lib}" -eq 0 && \
@@ -336,6 +380,10 @@ if [[ $is_script_sourced -eq 0 ]]; then
 
     check_options "$@"
 
+    if [[ "${enable_model_explorer}" -eq 1 ]]; then
+        check_model_explorer_python
+    fi
+
     if [[ "${#target_toolchains[@]}" -eq 0 ]]; then
         target_toolchains=("gnu")
     fi
@@ -418,6 +466,10 @@ if [[ $is_script_sourced -eq 0 ]]; then
         setup_ethos_u_tools
     fi
 
+    if [[ "${enable_model_explorer}" -eq 1 ]]; then
+        setup_model_explorer
+    fi
+
     log_step "main" "Setup complete"
     exit 0
 fi