mlia-model-explorer 0.1.1__tar.gz

mlia_model_explorer-0.1.1/.ci/model-explorer-public/README.md

@@ -0,0 +1,59 @@
+# Model Explorer [![PyPI version](https://badge.fury.io/py/ai-edge-model-explorer.svg)](https://badge.fury.io/py/ai-edge-model-explorer) [![npm version](https://badge.fury.io/js/ai-edge-model-explorer-visualizer.svg)](https://badge.fury.io/js/ai-edge-model-explorer-visualizer)
+
+Model Explorer offers an intuitive and hierarchical visualization of model
+graphs. It organizes model operations into nested layers, enabling users to
+dynamically expand or collapse these layers. It also provides a range of
+features to facilitate model exploration and debugging, including the ability to
+highlight input and output operations, overlay metadata on nodes, display layers
+in interactive pop-ups, perform searches, show identical layers, GPU-accelerated
+graph rendering, among others. It currently supports TFLite, TF, TFJS, MLIR, and
+PyTorch (Exported Program) model format, and provides an extension framework for
+developers to easily add support for additional formats.
+
+<img width="890" alt="Home page screenshot" src="screenshots/main_ui.png">
+
+<br>
+
+To start using Model Explorer, run:
+
+```shell
+$ pip install ai-edge-model-explorer
+$ model-explorer
+```
+
+Or give it a try on [Hugging Face](https://huggingface.co/spaces/google/model-explorer) (only support visualizing uploaded models)
+
+Please check out our [Wiki](https://github.com/google-ai-edge/model-explorer/wiki) for
+more details:
+
+- [Installation](https://github.com/google-ai-edge/model-explorer/wiki/1.-Installation)
+- [User Guide](https://github.com/google-ai-edge/model-explorer/wiki/2.-User-Guide)
+- [Command Line Guide](https://github.com/google-ai-edge/model-explorer/wiki/3.-Command-Line-Guide)
+- [API Guide](https://github.com/google-ai-edge/model-explorer/wiki/4.-API-Guide)
+- [Run in Colab Notebook](https://github.com/google-ai-edge/model-explorer/wiki/5.-Run-in-Colab-Notebook)
+- [Develop Adapter Extension](https://github.com/google-ai-edge/model-explorer/wiki/6.-Develop-Adapter-Extension)
+- [Limitations and Known Issues](https://github.com/google-ai-edge/model-explorer/wiki/7.-Limitations-and-Known-Issues)
+
+We invite you to participate in research studies on Model Explorer. Sign up [here](https://docs.google.com/forms/d/e/1FAIpQLScGOkQOIKmIzkt3P0ywhSfwbl-TRb2epEV5J8NTXEesZqc3vw/viewform).
+
+## NPM package
+
+The core visualizer component is available in the
+[ai-edge-model-explorer-visualizer](https://www.npmjs.com/package/ai-edge-model-explorer-visualizer)
+npm pacakge. See the [README.md](src/ui/custom_element_npm/README.md) for
+instructions and check out its [demos](src/custom_element_demos/).
+
+## Community-contributed adapters
+
+- ONNX Adapter: https://github.com/justinchuby/model-explorer-onnx
+- VGF Adapter: https://github.com/arm/vgf-adapter-model-explorer
+- TOSA Adapter: https://github.com/arm/tosa-adapter-model-explorer
+
+## Contributions
+
+You are invited to create custom adapters to add support for additional model formats. Please refer to our [Develop Adapter Extension](https://github.com/google-ai-edge/model-explorer/wiki/6.-Develop-Adapter-Extension) guide. We will gladly consider pull requests to add links to your adapter's GitHub repository and PyPI package to this README.
+
+## Resources
+
+- [Introduction video](https://youtu.be/DgkLKybBVcs?si=eLmNTE66RlKkLQcT) on YouTube
+- [Blog post](https://research.google/blog/model-explorer/) on Google Research Blog

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/builtin-adapter/README.md

@@ -0,0 +1,55 @@
+# Model Explorer Adapter
+
+The Model Explorer Adapter provides graph extraction and visualization
+conversion for ML models (TensorFlow SavedModel, GraphDef, FlatBuffer/TFLite,
+StableHLO/MLIR) to Model Explorer's visualization JSON format.
+
+It is implemented as a stable C-ABI library
+(`libai_edge_model_explorer_adapter.so` / `.dylib`) with a pure Python `ctypes`
+FFI wrapper for universal ABI stability across Python versions without pybind11
+compile-time matrix bloat.
+
+## Install from PyPI
+
+Install `ai-edge-model-explorer-adapter` via pip from PyPI. For example, in a
+Python virtual environment:
+
+```bash
+% python3 -m venv ~/tmp/venv
+% source ~/tmp/venv/bin/activate
+(venv) $ pip install ai-edge-model-explorer-adapter
+```
+
+## Use the Package
+
+After installation, the package can be imported directly:
+
+```python
+import ai_edge_model_explorer_adapter as adapter
+
+config = adapter.VisualizeConfig()
+json_str = adapter.ConvertFlatbufferDirectlyToJson(config, "model.tflite")
+print(json_str)
+```
+
+## Build and Install Locally
+
+### Declarative Bazel Build
+
+Build the Python wheel directly using Bazel:
+
+```bash
+bazel build -c opt //python/ai_edge_model_explorer_adapter:wheel
+```
+
+The resulting wheel is located under `bazel-bin/`:
+`bazel-bin/python/ai_edge_model_explorer_adapter/`
+
+### Install
+
+Install the resulting wheel via pip:
+
+```bash
+(venv) $ pip install \
+  bazel-bin/python/ai_edge_model_explorer_adapter/*.whl
+```

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/custom_element_demos/README.md

@@ -0,0 +1,27 @@
+# Demos for Model Explorer Visualizer NPM package
+
+This directory contains four demos showcasing the usage of the
+`<model-explorer-visualizer>` custom element from the
+[ai-edge-model-explorer-visualizer](https://www.npmjs.com/package/ai-edge-model-explorer-visualizer)
+npm package in different JavaScript frameworks and environments.
+See their respective README.md files for more details. Here is a summary:
+
+**Vanilla JS**:
+
+  * Use `<model-explorer-visualizer>` in plain JavaScript.
+  * How to set custom location for static files needed by the visualizer.
+
+**Vanilla TS**:
+
+  * Use `<model-explorer-visualizer>` in plain TypeScript.
+  * How to set custom location for the worker script needed by the visualizer.
+
+**Next.js**:
+
+  * Use `<model-explorer-visualizer>` in a Next.js application.
+  * Imports the visualizer module within a `useEffect` hook.
+
+**Angular**:
+
+  * Use `<model-explorer-visualizer>` in an Angular application.
+  * Includes a left-side panel showcasing various visualizer APIs.

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/custom_element_demos/angular/README.md

@@ -0,0 +1,19 @@
+# Demo
+
+This demo uses the `<model-explorer-visualizer>` custom element in an Angular
+application. Run the commands below to build the app and start a local dev
+server.
+
+```
+$ npm install
+$ npm run start
+```
+
+It should open the page `http://localhost:4200` automatically in browser.
+
+# Notes
+
+- This demo has a left-side panel to showcase how various visualizer APIs work.
+  See comments in `src/app/app.component.ts` for more details.
+- This demo uses symlinks to make the `worker.js` file and `static_files`
+  directory from `node_modules` available under the `public` directory.

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/custom_element_demos/nextjs/README.md

@@ -0,0 +1,21 @@
+# Demo
+
+This demo uses the `<model-explorer-visualizer>` custom element in a Next.js
+application. Run the commands below to build the app and start a local dev
+server.
+
+```
+$ npm install
+$ npm run dev
+```
+
+Visit `http://localhost:3000`
+
+# Notes
+
+- The custom element works in the client-side script.
+- Import the visualizer package in `useEffect` instead of importing it at top
+  level.
+- This demo uses symlinks to make the `worker.js` file and `static_files`
+  directory from `node_modules` available under the `public` directory.
+

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/custom_element_demos/vanilla_js/README.md

@@ -0,0 +1,25 @@
+# Demo
+
+This demo uses the `<model-explorer-visualizer>` custom element in vanilla JS.
+Run the command below to prepare and launch the demo in a browser tab.
+
+```
+$ ./build_and_deploy.sh
+```
+
+It should open the page `http://localhost:8080/dist` automatically in browser.
+
+# Notes
+
+- Load `https://unpkg.com/ai-edge-model-explorer-visualizer@latest` in a script tag in `index.html`.
+- Download `https://unpkg.com/ai-edge-model-explorer-visualizer@latest/dist/worker.js` and place it in the
+   same directory as index.html.
+- To enable the visualizer to load static files from `unpkg`, set
+   `modelExplorer.assetFilesBaseUrl` to `https://unpkg.com/ai-edge-model-explorer-visualizer@latest/dist/static_files`.
+   Alternatively, you can download the `static_files` directory and place it in
+   the same directory as `index.html` for local serving.
+
+Check out file comments in `src/` for more details.
+
+
+

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/custom_element_demos/vanilla_ts/README.md

@@ -0,0 +1,22 @@
+# Demo
+
+This demo uses the `<model-explorer-visualizer>` custom element in vanilla TS.
+Run the command below to build and launch the demo in a browser tab.
+
+```
+$ npm run build_and_deploy
+```
+
+It should open the page `http://localhost:8080/dist` automatically in browser.
+
+# Notes
+
+- Import `ai-edge-model-explorer-visualizer` in the main typescript file.
+- This demo uses symlinks to make the `worker.js` file and `static_files`
+  directory from `node_modules` available in the same directory as `index.html`.
+- The `worker.js` file is linked to `dist/my_worker_path/worker.js` instead of
+  the default location (`dist/worker.js`). To ensure the custom element can
+  load it successfully, the main script must set
+  `modelExplorer.workerScriptPath` to this path.
+
+Check out file comments in `src/` for more details.

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/example_adapters/graphviz_dot_adapter/README.md

@@ -0,0 +1,30 @@
+This is an example adapter extension that adds basic support for
+[GraphViz DOT](https://graphviz.org/pdf/dotguide.pdf) format to Model Explorer.
+It uses [pydot](https://pypi.org/project/pydot/) to parse the input `.dot` file
+and converts it into Model Explorer graphs. It only supports a subset of
+features in DOT, including node labels, edge connections, and
+subgraphs/clusters.
+
+Check out the
+[Develop Adapter Extension](https://github.com/google-ai-edge/model-explorer/wiki/6.-Develop-Adapter-Extension)
+wiki to learn more.
+
+<img src="screenshots/graphviz_dot_adapter.png" width="890">
+
+<br>
+
+# Run it locally
+
+Run the following commands under the top `graphviz_dot_adapter` directory:
+
+```shell
+# Setup python venv.
+$ python3 -m venv venv
+$ source venv/bin/activate
+
+# Run Model Explorer with the "graphviz_dot_adapter" extension.
+#
+# Note the "." at the end.
+$ pip install -e .
+$ model-explorer example.dot --extension=graphviz_dot_adapter
+```

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/example_adapters/graphviz_dot_adapter/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "graphviz-dot-adapter"
+version = "0.0.1"
+
+dependencies = [
+  "ai-edge-model-explorer",
+  "pydot",
+]

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/example_adapters/my_adapter/README.md

@@ -0,0 +1,26 @@
+This is an example adapter extension used in the
+[Develop Adapter Extension](https://github.com/google-ai-edge/model-explorer/wiki/6.-Develop-Adapter-Extension)
+wiki.
+
+This adapter adds support for a imaginary `.test` model format and always
+returns the same graph:
+
+<img src="screenshots/my_adapter_graph.png" width="562">
+
+<br>
+
+# Run it locally
+
+Run the following commands under the top `my_adapter` directory:
+
+```shell
+# Setup python venv.
+$ python3 -m venv venv
+$ source venv/bin/activate
+
+# Run Model Explorer with the "my_adapter" extension.
+#
+# Note the "." at the end.
+$ pip install -e .
+$ model-explorer model.test --extension=my_adapter
+```

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/example_adapters/my_adapter/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "my-adapter"
+version = "0.0.1"
+
+dependencies = [
+  "ai-edge-model-explorer",
+]

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/example_node_data_providers/my_ndp/README.md

@@ -0,0 +1,24 @@
+# Run it locally
+
+Run the following commands under the top `my_ndp` directory:
+
+```shell
+# At <repo_root>/src/example_node_data_providers/my_ndp:
+#
+# Setup python venv.
+$ python3 -m venv venv
+$ source venv/bin/activate
+
+# Run Model Explorer with the "my_ndp" extension.
+#
+# Note the "." at the end. This will also install ai-edge-model-explorer.
+$ pip install -e .
+$ model-explorer coco-ssd.json --extension=my_ndp
+```
+
+In the Model Explorer UI, click the "+ Add per-node data" button in the toolbar.
+This will open a menu where you should select "My test node data provider" to
+launch the configuration dialog. The dialog allows you to try out different
+config editors; however, for this extension, only the "Start color" and
+"End color" fields will be used to specify the node data's gradient colors.
+Set these two colors to distinct values, and then click Run to view the results.

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/example_node_data_providers/my_ndp/pyproject.toml

@@ -0,0 +1,7 @@
+[project]
+name = "my-ndp"
+version = "0.0.1"
+
+dependencies = [
+  "ai-edge-model-explorer",
+]

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/server/README.md

@@ -0,0 +1,9 @@
+# Model Explorer local server
+
+## Local development
+
+```
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ ./scripts/setup_local_dev.sh
+```

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/server/package/README.md

@@ -0,0 +1,26 @@
+# Model Explorer
+
+Model Explorer offers an intuitive and hierarchical visualization of model
+graphs. It organizes model operations into nested layers, enabling users to
+dynamically expand or collapse these layers. It also provides a range of
+features to facilitate model exploration and debugging, including the ability to
+highlight input and output operations, overlay metadata on nodes, display layers
+in interactive pop-ups, perform searches, show identical layers, GPU-accelerated
+graph rendering, among others. It currently supports TFLite, TF, TFJS, MLIR, and
+PyTorch (Exported Program) model format, and provides an extension framework for
+developers to easily add support for additional formats.
+
+![](https://raw.githubusercontent.com/google-ai-edge/model-explorer/main/screenshots/main_ui.png)
+
+<br>
+<br>
+
+Please check out our [Wiki](https://github.com/google-ai-edge/model-explorer/wiki) for
+more details:
+
+- [Installation](https://github.com/google-ai-edge/model-explorer/wiki/1.-Installation)
+- [User Guide](https://github.com/google-ai-edge/model-explorer/wiki/2.-User-Guide)
+- [Command Line Guide](https://github.com/google-ai-edge/model-explorer/wiki/3.-Command-Line-Guide)
+- [API Guide](https://github.com/google-ai-edge/model-explorer/wiki/4.-API-Guide)
+- [Run in Colab Notebook](https://github.com/google-ai-edge/model-explorer/wiki/5.-Run-in-Colab-Notebook)
+- [Develop Adapter Extension](https://github.com/google-ai-edge/model-explorer/wiki/6.-Develop-Adapter-Extension)

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/server/package/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "ai-edge-model-explorer"
+version = "0.1.32"
+authors = [
+  { name="Google LLC", email="opensource@google.com" },
+]
+description = "A modern model graph visualizer and debugger"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+   "Programming Language :: Python :: 3.9",
+   "Programming Language :: Python :: 3.10",
+   "Programming Language :: Python :: 3.11",
+   "Programming Language :: Python :: 3.12",
+   "Programming Language :: Python :: 3.13",
+   "License :: OSI Approved :: Apache Software License",
+]
+dependencies = [
+  "flask",
+  "ipython",
+  # Skip on windows.
+  "ai-edge-model-explorer-adapter ~= 0.1.14; sys_platform != 'win32'",
+  "dacite",
+  "packaging",
+  "portpicker",
+  "requests",
+  "termcolor",
+  "typing-extensions",
+  "numpy",
+  "watchdog",
+]
+
+[project.scripts]
+model-explorer = "model_explorer.cmdline:main"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+# Include all files in "web_app" dir.
+[tool.setuptools.package-data]
+"model_explorer.web_app" = ["**/*"]

mlia_model_explorer-0.1.1/.ci/model-explorer-public/src/ui/README.md

@@ -0,0 +1,87 @@
+An Angular project for Model Explorer UI.
+
+# Local development
+
+## One-time setup
+
+Install Angular CLI and packages:
+
+```
+$ npm install -g @angular/cli
+$ npm install
+```
+
+## Run dev server
+
+First, start the Model Explorer python server locally for handling API requests.
+Check out the [Installation Guide](https://github.com/google-ai-edge/model-explorer/wiki/1.-Installation)
+if needed.
+
+```
+$ model-explorer --no_open_in_browser
+```
+
+Then, start the Angular dev server:
+
+```
+$ ng serve
+```
+
+Access the app at http://localhost:4200 after the Angular dev server starts.
+
+<br>
+
+> [!IMPORTANT]
+> The python server starts at port 8080 by default, which is also the default
+> port the Angular dev server sends API requests to. See below if you want to
+> use a different port.
+
+To use a different port:
+
+Start the python server at the port:
+
+```
+$ model-explorer --port=<port_number> --no_open_in_browser
+```
+
+Update the port number in [`src/proxy.conf.json`](https://github.com/google-ai-edge/model-explorer/blob/main/src/ui/src/proxy.conf.json),
+then start the Angular dev server.
+
+## Run demo app without python server
+
+This Angular project also has a demo page showing the main
+[visualizer component](https://github.com/google-ai-edge/model-explorer/tree/main/src/ui/src/components/visualizer) directly. It renders the pre-converted model graph JSON files from
+a TFLite model and a TF model. This allows you to experiment with the visualizer
+code without going through the model conversion process.
+
+You only need to run the Angular dev server to see the demo page.
+
+
+```
+$ ng serve
+```
+
+Then visit the demo page at http://localhost:4200/demo
+
+# Deployment
+
+Run the following command to build the Angular app and update the corresponding
+files in the python package (`src/server/package/src/model_explorer/web_app`).
+
+```
+$ npm run deploy
+```
+
+<br>
+
+> [!NOTE]
+> On Linux host, install `rollup` manually if you see the
+> `Cannot find module @rollup/rollup-linux-x64-gnu` error.
+>
+> `$ npm install @rollup/rollup-linux-x64-gnu`
+
+# Contributions
+
+We are not currently accepting community contributions to Model Explorer UI
+(except for links to community-built adapters). Please submit feature requests
+or proposals to collaborate via the Issue Tracker.