Metadata-Version: 2.4
Name: executorch-extension-model-explorer
Version: 0.1.0
Summary: Combined Model Explorer extension package for ExecuTorch PTE, ETRecord, and ETDump artifacts
License-Expression: Apache-2.0
Keywords: model-explorer,executorch,pte,etrecord,etdump,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ai-edge-model-explorer<0.2.0,>=0.1.28
Requires-Dist: executorch>=1.2.0
Requires-Dist: pte-adapter-model-explorer>=0.1.2
Requires-Dist: etrecord-adapter-model-explorer>=0.1.0
Requires-Dist: etdump-data-provider-model-explorer>=0.1.0
Requires-Dist: vgf-adapter-model-explorer>=0.4.1
Requires-Dist: tosa-adapter-model-explorer>=0.1.0
Requires-Dist: flatbuffers>25.9
Dynamic: license-file

<!---
SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its affiliates <open-source-office@arm.com>
SPDX-License-Identifier: Apache-2.0
--->

# ExecuTorch Extension Model Explorer

ExecuTorch Extension Model Explorer is a combined extension package for
[Model Explorer](https://github.com/google-ai-edge/model-explorer). It registers
adapters and data providers for inspecting ExecuTorch model artifacts and
profiling data in one package:

- [`PTEAdapter`](https://github.com/arm/pte-adapter-model-explorer)
  visualizes `.pte` model files.
- [`ETRecordAdapter`](https://github.com/arm/etrecord-adapter-model-explorer)
  visualizes `.etrecord` graph files.
- [`ETDumpProfilingOverlayProvider`](https://github.com/arm/etdump-data-provider-model-explorer)
  overlays runtime profiling data from `.etdp` or `.etdump` files onto ETRecord
  graphs.

## Supported File Types

| File type | Component | Purpose |
| --- | --- | --- |
| `.pte` | PTE Adapter | Visualize ExecuTorch program files. |
| `.etrecord` | ETRecord Adapter | Visualize exported ExecuTorch graph structure and metadata. |
| `.etdp`, `.etdump` | ETDump Profiling Overlay | Add per-node runtime latency data to ETRecord graphs. |

## Requirements

- Python >=3.10, <3.13
- Model Explorer, provided by `ai-edge-model-explorer`
- ExecuTorch Python packages for ETRecord and ETDump workflows
- PTE delegate support packages declared by this project:
  `vgf-adapter-model-explorer`, `tosa-adapter-model-explorer`, and
  `flatbuffers`

## Installation

For local development from this repository:

```bash
scripts/install-editable.sh
```

Install the published package from PyPI:

```bash
pip install executorch-extension-model-explorer
```

## Usage

Launch Model Explorer with this combined extension package enabled:

```bash
model-explorer --extensions=executorch_extension_model_explorer
```

To load individual adapters or providers, pass the extension names directly:

```bash
model-explorer --extensions=pte_adapter_model_explorer
model-explorer --extensions=etrecord_adapter_model_explorer
model-explorer --extensions=etrecord_adapter_model_explorer,etdump_data_provider_model_explorer
```

### PTE Adapter

Open a `.pte` file in Model Explorer to inspect the ExecuTorch program. The PTE
adapter includes delegate support for Arm Ethos-U, Arm VGF, and XNNPACK. See the
[PTE adapter documentation](https://github.com/arm/pte-adapter-model-explorer)
for details and schema regeneration notes.

### ETRecord Adapter

Open an `.etrecord` file in Model Explorer to inspect exported ExecuTorch graph
structure, metadata, connections, inputs, and outputs. See the
[ETRecord adapter documentation](https://github.com/arm/etrecord-adapter-model-explorer)
for details.

### ETDump Data Provider

After opening an `.etrecord` graph, click `Add per-node data`, select
`ETDump Profiling Overlay`, upload an `.etdp` or `.etdump` file, and run the
provider. The overlay maps runtime latency metrics onto matching ETRecord graph
nodes. See the
[ETDump data provider documentation](https://github.com/arm/etdump-data-provider-model-explorer)
for details and mock artifact tooling.

## Development

Install the package in editable mode, then run the test suite with pytest:

```bash
scripts/install-editable.sh
scripts/test-all.sh
```

For coordinated development across all leaf repos, keep the adapter repositories
as sibling checkouts and install them in editable mode before the umbrella
package:

```bash
scripts/install-local-adapters.sh
```

The umbrella wheel uses the package versions pinned in `pyproject.toml`.
Local adapter checkouts are for multi-repo development and adapter-specific
testing; they are not the release pin.

Run adapter-specific tests from each adapter repository root so their local
fixtures and pytest configuration are resolved correctly.

Development dependency groups are declared in `pyproject.toml` for test,
coverage, lint, type-checking, and build tools.

### CI

Pull requests and pushes to `main` run the aggregate CI workflow. It
installs this package in editable mode, then runs Ruff, Pyright, and the
aggregate pytest suite. The workflow also builds a wheel after tests pass.

Pushes to `main` publish an internal development build to the configured
internal PyPI/Artifactory repository. Release tags matching `v*.*.*` publish to
public PyPI and create a GitHub release.

Use the `Trigger Release` workflow to cut a release from the private repository.
It calculates the next version with git-cliff, updates `pyproject.toml`, pushes
the version bump commit, and pushes the release tag. The tag push then triggers
the publish path.

### Dependency update policy

This repository pins the three adapter/provider packages in `pyproject.toml`.
By default, update those dependency versions only when a leaf package is
released, not after every merge to a leaf repository.

Use the helper script for local dependency pin updates:

```bash
python scripts/update-dependency-pin.py etrecord-adapter-model-explorer v0.2.0
```

The same update can be automated through the `Update dependency pin` workflow.
Leaf release workflows can trigger it with a `repository_dispatch` event named
`update-dependency` and a payload containing `dependency` or `name`, plus
`version` or `tag`. The workflow also accepts the old `update-submodule`
dispatch name for compatibility, but it now updates `pyproject.toml`.

## Trademark Notice

This project uses some of the Arm product, service, or technology trademarks,
as listed in the [Trademark List](https://www.arm.com/company/policies/trademarks/arm-trademark-list),
in accordance with the Arm [Trademark Use Guidelines](https://www.arm.com/company/policies/trademarks/guidelines-trademarks).

Subsequent uses of these trademarks throughout this repository do not need to
be prefixed with the Arm word trademark.

## Contributions

We are not accepting direct contributions at this time. If you have feedback or
feature requests, please use the repository issues section.
