Metadata-Version: 2.5
Name: mlia
Version: 0.12.3
Summary: ML Inference Advisor
Project-URL: Homepage, https://github.com/arm/mlia.git
Author-email: Arm Ltd <mlia@arm.com>
License-Expression: Apache-2.0
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/MIT.txt
Keywords: arm,ethos-u,ml,tflite
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: importlib-metadata>=8.7.0; python_version < '3.10'
Requires-Dist: numpy>=2.0.0
Requires-Dist: packaging>=24.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: requests~=2.32.3
Requires-Dist: rich~=13.7.1
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Requires-Dist: typer<0.26,>=0.24.2
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == 'torch'
Description-Content-Type: text/markdown

<!---
SPDX-FileCopyrightText: Copyright 2022-2026, Arm Limited and/or its affiliates.
SPDX-License-Identifier: Apache-2.0
--->

# ML Inference Advisor

ML Inference Advisor (MLIA) helps AI developers evaluate model compatibility
and performance for supported inference targets. The core `mlia` package
provides the shared CLI, public Python API, backend management, and standardized
output model. Installed plugins register target, backend, converter, and
post-analysis capabilities.

## Table of Contents

- [Documentation](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#documentation)
- [Plugin model](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#plugin-model)
- [Installation](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#installation)
- [Quick start](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#quick-start)
- [Python API](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#python-api)
- [Reporting bugs](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#reporting-bugs)
- [Configuration](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#configuration)
- [Development](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#development)
- [Getting support](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#getting-support)
- [Reporting vulnerabilities](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#reporting-vulnerabilities)
- [Releases](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#releases)
- [License](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#license)
- [Inclusive language commitment](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#inclusive-language-commitment)
- [Trademarks and copyrights](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#trademarks-and-copyrights)

## Documentation

Structured repository documentation lives in [docs/README.md](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/docs/README.md).
Use the core docs for:

- Shared CLI guidance: [docs/source/cli.md](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/docs/source/cli.md).
- Backend discovery and installation:
  [docs/source/backends.md](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/docs/source/backends.md).
- Output structure and JSON results:
  [docs/source/metrics.md](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/docs/source/metrics.md).
- Architecture and package boundaries:
  [docs/source/overview.md](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/docs/source/overview.md),
  [docs/source/high_level_architecture.md](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/docs/source/high_level_architecture.md),
  and [docs/source/execution_flow.md](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/docs/source/execution_flow.md).

Target-specific, backend-specific, and converter-specific detail belongs in the
documentation for the plugin package that owns that functionality.

## Plugin model

`mlia` is the core package. Targets, backends, and converters are provided
through separate plugin wheels.

MLIA uses the following plugin model:

- `mlia` provides the command-line experience and shared output model.
- Plugin packages add target definitions, backend implementations, and converter
  paths.
- MLIA discovers those plugins at runtime and exposes them through the same CLI.

### Target plugins

- [MLIA Ethos-U](https://github.com/arm/mlia-ethos-u)
  (`mlia-ethos-u`) adds Ethos-U target profiles and the Vela and Corstone
  backends for compatibility and performance analysis.
- [MLIA Neural Technology](https://github.com/arm/mlia-neural-technology)
  (`mlia-neural-technology`) adds Arm Neural Technology target profiles and
  backends for performance estimation and performance analysis.

### Converter plugins

- [MLIA PyTorch Converter](https://github.com/arm/mlia-converters-pytorch)
  (`mlia-converters-pytorch`) converts PyTorch models into artifacts used by
  supported MLIA target flows.
- [MLIA LiteRT Converter](https://github.com/arm/mlia-converters-litert)
  (`mlia-converters-litert`) converts LiteRT / TensorFlow Lite `.tflite` models
  into TOSA artifacts for supported MLIA target flows.

Install only the plugin packages you need, then use the discovery commands to
see what is available in the current environment:

```bash
mlia target list
mlia backend list
```

## Installation

It is recommended to use a virtual environment for MLIA installation.
A typical setup requires:

- Ubuntu 22.04 LTS or another compatible Linux environment
- Python 3.10 or newer
- `libpython3.10-dev` when required by your environment

Most users should install a [target plugin](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#target-plugins). Target plugins
declare `mlia` as a dependency, so installing one also installs a compatible
version of the MLIA core package. For example:

```bash
pip install mlia-ethos-u
```

If your workflow requires model conversion, install the relevant
[converter plugin](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/README.md#converter-plugins) alongside the target plugin:

```bash
pip install mlia-ethos-u mlia-converters-pytorch
```

Install the core package directly only when you do not need a target plugin:

```bash
pip install mlia
```

See each plugin's documentation for supported targets, models, and any
additional setup.

## Quick start

Check that MLIA is installed correctly:

```bash
mlia --help
```

A typical run looks like this:

```bash
mlia check my_model.tflite --target-profile <target-profile> --performance
```

Useful discovery commands:

```bash
mlia target list
mlia backend list
mlia check --help
```

Use custom target profiles by passing a TOML file path:

```bash
mlia check my_model.tflite --target-profile ./my_target_profile.toml
```

If you are new to the plugin-based model, the safest first pattern is:

1. Install the target plugin and any converter plugin you need.
2. Confirm target and backend discovery with `mlia target list` and
   `mlia backend list`.
3. Run one simple `mlia check` command, then add backend-specific options as
   needed.

## Python API

MLIA also provides a Python API for programmatic compatibility and performance
analysis. The main entry point is `run_advisor()`, which mirrors the CLI
`check` workflow and returns standardized output as a Python `dict`.

```python
from pathlib import Path

from mlia import run_advisor

result = run_advisor(
    advice_category="performance",
    target_profile="<target-profile>",
    model=Path("my_model.tflite"),
)

print(result["schema_version"])
print(result["results"])
```

Other public helpers include:

- `list_targets()`
- `list_target_profiles()`
- `list_backends()`
- `list_backend_options()`
- `supported_backends(target_profile)`

If you need `torch.nn.Module` inputs, install the PyTorch converter plugin:

```bash
pip install mlia-converters-pytorch
```

The Python API uses the same installed target and backend plugins as the CLI.

## Reporting bugs

Report bugs by creating a GitHub issue. Use the
[`arm/mlia` issue tracker](https://github.com/arm/mlia/issues) by default,
including when you are not sure which repo owns the problem.

Only file an issue in a plugin repository if the bug is clearly and
specifically isolated to that plugin.

## Configuration

MLIA reads user configuration from the platform-specific configuration
directory provided by `platformdirs`. On Linux this is normally
`~/.config/mlia/config.toml`.

Supported top-level TOML keys are:

- `color` (`bool`): enable or disable colored terminal output.
- `backend_options` (`table`): configuration passed to installed backends.
- `core` (`table`): settings owned by the core application.
- `filtering` (`table`): standardized-output filtering settings. Its optional
  `collapse` value is an array of tables.
- `plugins` (`table`): settings keyed by post-analysis plugin name. Each plugin's
  value is a table owned and validated by that plugin.

Entity collapse can be configured with an array of rules:

```toml
[[filtering.collapse]]
kind = "code_stack"
attribute = "file"
globs = ["*/generated/*", "*/site-packages/*"]
```

Each rule selects an entity kind, a string attribute, and one or more glob
patterns. Core combines these rules with defaults supplied by the backend before
deriving source-line entities and projecting breakdowns.

Post-analysis plugins receive only their own settings table:

```toml
[plugins.example]
output_format = "custom"
```

The plugin registered as `example` receives the contents of `plugins.example`
and is responsible for validating them.

MLIA follows common CLI environment variables where they map cleanly to existing
options:

- `DEBUG`: enable verbose output by default. Passing `--debug` has the same
  effect.
- `NO_COLOR`: disable colored terminal output.
- `MLIA_NO_COLOR`: disable colored terminal output for MLIA specifically.
- `COLUMNS`: set the terminal width used for interactive output. Redirected
  output is rendered wide so the receiving terminal or tool can wrap it.

MLIA can read environment variables from `.env` files in parent directories.

When an option is available through more than one source, MLIA applies values
in this order:

1. Command-line flags.
2. The running shell's environment variables.
3. Project-level environment variables.
4. User-level configuration.
5. Built-in defaults.

## Development

Install `uv`, then sync dependencies for local development:

```bash
uv sync --group dev
```

Common commands:

```bash
uv run pre-commit run --all-files --hook-stage=push
uv run pytest --no-success-flaky-report -m "not slow" tests/
uv run pytest --no-success-flaky-report tests/
uv build
```

Wheel builds include a CycloneDX SBOM in the wheel's
`mlia-<version>.dist-info/sboms/` directory.

## Getting support

In case you need support or want to report an issue, give us feedback or simply
ask a question about MLIA, please send an email to <mlia@arm.com>.

Alternatively, use the
[AI and ML forum](https://community.arm.com/support-forums/f/ai-and-ml-forum)
to get support by marking your post with the **MLIA** tag, or tag the @mlia
team directly for assistance.

## Reporting vulnerabilities

Information on reporting security issues can be found in
[Reporting vulnerabilities](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/SECURITY.md).

## Releases

Latest changes and release history can be found in [MLIA releases](https://github.com/arm/mlia/releases).

## License

ML Inference Advisor is licensed under [Apache License 2.0](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/LICENSES/Apache-2.0.txt)
unless otherwise indicated. This project contains software under a range of
permissive licenses, see [LICENSES](https://github.com/arm/mlia/blob/1bca4c652e40fc5b1bb11f7cac4b21ebd2222893/LICENSES/).

## Inclusive language commitment

This product conforms to Arm's inclusive language policy and, to the best of
our knowledge, does not contain any non-inclusive language.

If you find something that concerns you, email <terms@arm.com>.

## Trademarks and copyrights

- Arm, Arm Ethos-U, Arm Cortex-A, Arm Cortex-M, and Arm Corstone are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the U.S. and/or elsewhere.
- TensorFlow is a trademark of Google LLC.
- PyTorch and ExecuTorch are trademarks of The Linux Foundation.
- Keras is a trademark of Francois Chollet.
- Linux is the registered trademark of Linus Torvalds in the U.S. and elsewhere.
- Python is a registered trademark of the PSF.
- Ubuntu is a registered trademark of Canonical.
- Microsoft and Windows are trademarks of the Microsoft group of companies.
