Metadata-Version: 2.2
Name: tosa-tools
Version: 2026.2.1
Summary: TOSA Tools: serialization library, reference model, optional MLIR translator
Author: Arm Ltd.
License: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Project-URL: Homepage, https://gitlab.arm.com/tosa/tosa-tools
Project-URL: Issues, https://gitlab.arm.com/tosa/tosa-tools/-/issues
Requires-Python: >=3.10
Requires-Dist: numpy<2.2,>=1.26
Requires-Dist: flatbuffers==25.2.10
Requires-Dist: jsonschema==4.24.0
Requires-Dist: ml-dtypes==0.5.1
Requires-Dist: semver==3.0.4
Provides-Extra: dev
Requires-Dist: pre-commit==3.8.0; extra == "dev"
Requires-Dist: pytest==8.4.1; extra == "dev"
Description-Content-Type: text/markdown

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

# TOSA Tools

A toolkit for working with the *Tensor Operator Set Architecture (TOSA) Specification (<https://git.mlplatform.org/tosa/specification.git/>)*, providing serialization, reference implementation, and MLIR translation capabilities.

# Introduction

TOSA Tools is a composite project that integrates three main components:

- [reference_model](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/reference_model/README.md) – a reference implementation of TOSA operators.
- [serialization](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/serialization/README.md) – provides methods to read and write serialized TOSA graphs.
- [mlir_translator](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/mlir_translator/README.md) – implements translators between the TOSA MLIR dialect and serialized representations.

Each subfolder contains its own README with more detailed information.

## PyPI package

From v2026.02.0 onward, the `tosa-tools` Python package is published on PyPI.
For most users, the quickest start is:

```bash
python -m pip install tosa-tools
```

This installs the Python APIs and command-line entrypoints from all the components (serialization + reference model + MLIR translator). For a concise list of the Python modules, executables, console scripts and shared libraries installed by the package, see [PYTHON_PACKAGE.md](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/PYTHON_PACKAGE.md).

## Prerequisites

### Platform support

The following platforms are supported:

| Platform | Architecture | Support level |
|----------|--------------|---------------|
| Linux    | x86_64       | release |
| Linux    | aarch64      | experimental |
| Windows (r) | x86_64    | experimental |
| macOS (r)   | aarch64   | experimental |

For build instructions see README.md for individual components.

### System Requirements

| Tool      | Version           | Note                                      |
|-----------|-------------------|-------------------------------------------|
| Python    | 3.10 or later     | tested with 3.12.0                        |
| CMake     | 3.16 or later     | tested with 3.30                          |

### External Dependencies

#### LLVM/MLIR

The TOSA MLIR Translator must be linked against a build of [LLVM](https://llvm.org/) with the [MLIR](https://mlir.llvm.org/getting_started/) project enabled. Currently, the TOSA MLIR Translator aims to be compatible with the `main` branch of LLVM. However, when breaking API changes are introduced in LLVM/MLIR, compatibility may not be guaranteed. We regularly update the tested SHA; see [ci/vars/llvm-sha.yml](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/ci/vars/llvm-sha.yml) for the current SHA.

## Quick Build (POSIX)

Build all projects with default configuration:

```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

### Selective Build

Use `TOSA_ENABLE_PROJECTS` to build specific components:

**Build only serialization library:**
```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS=serialization
cmake --build build
```

**Build serialization and reference model:**
```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS="serialization;reference_model"
cmake --build build
```

**Build MLIR translator:**
```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS="mlir_translator" \
    -DMLIR_TOSA_OPT=ON \
    -DMLIR_DIR=${LLVM_BUILD}/lib/cmake/mlir \
    -DLLVM_DIR=${LLVM_BUILD}/lib/cmake/llvm
cmake --build build
```

**Build all projects (including MLIR translator):**
```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DTOSA_ENABLE_PROJECTS=all \
    -DMLIR_TOSA_OPT=ON \
    -DMLIR_DIR=${LLVM_BUILD}/lib/cmake/mlir \
    -DLLVM_DIR=${LLVM_BUILD}/lib/cmake/llvm
cmake --build build
```

**Note:**
The MLIR translator requires MLIR to be available on your system. It is not enabled by default.
LLVM_BUILD must be absolute path to llvm-project build directory.

### Debug Build

For debug symbols:
```bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DTOSA_ENABLE_PROJECTS=reference_model
cmake --build build
```


## Build and install with pip

The Python package is built with `scikit-build-core`, which drives a CMake build under the hood.
This means `pip install` will compile native code and therefore requires a working C/C++ toolchain.

If you just want the prebuilt package, use `python -m pip install tosa-tools` as shown above.
The steps below are for building from source.

**Note:** Starting with release `2026.05.0`, the tooling to build/install the individual component
Python packages from subdirectories will be removed. Use the unified `tosa-tools` package from the
repository root (`python -m pip install .`).

### Install default components (serialization + reference model)

This uses the default CMake definitions from `pyproject.toml`.

```bash
python -m venv .venv
source .venv/bin/activate

python -m pip install -U pip

# Build + install from the current checkout
python -m pip install . -v -Cbuild-dir=build/pip-install
```

### Install with MLIR translator enabled

To build the MLIR translator you need a compatible LLVM/MLIR build.
The tested LLVM commit is pinned in [ci/vars/llvm-sha.yml](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/ci/vars/llvm-sha.yml).

Install `tosa-tools` with the required CMake config settings:

```bash
python -m pip install . -v -Cbuild-dir=build/pip-install \
    --config-settings=cmake.define.TOSA_ENABLE_PROJECTS="serialization;reference_model;mlir_translator" \
    --config-settings=cmake.define.MLIR_TOSA_OPT=ON \
    --config-settings=cmake.define.MLIR_DIR="${LLVM_BUILD}/lib/cmake/mlir" \
    --config-settings=cmake.define.LLVM_DIR="${LLVM_BUILD}/lib/cmake/llvm"
```

### Build a wheel locally (optional)

```bash
python -m pip wheel . -w dist -v -Cbuild-dir=build/pip-wheel
python -m pip install --no-deps dist/*.whl
```

# Development Environment

For a consistent setup, use the provided Docker configuration for development. This mirrors the CI environment closely. Please refer to the [CI README](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/ci/README.md) for more details.


## Pre-Commit Checks

Before pushing a commit, pre-commit checks must be run to ensure conformity.

**NOTE**: All commits pushed to remote must adhere to the structured commit format, please refer to [CONTRIBUTING.md](https://git.gitlab.arm.com/tosa/tosa-tools/-/blob/v2026.02.1/CONTRIBUTING.md) for detailed guidelines.

```bash
pre-commit install
pre-commit run --all
```

# Versioning

This project uses Calendar Versioning ([CalVer](https://calver.org/)) in the format: `YYYY.0M.Micro[.Modifier]`

- **YYYY** – 4-digit release year (e.g., 2025)
- **0M** – 2-digit Zero-padded release month (e.g., 07 for July)
- **Micro** – The third and usually final number in the version. Sometimes referred to as the "patch" segment.
- **Modifier** - Optional text tag used to signify extra information
about the build.
  - no tag (empty string) - builds produced for release will have no tag at all.

The `main` branch is used as the active development branch for the next
version.

# License

The TOSA Tools components are licensed as follows:

- **TOSA Serialization Library:** Apache-2.0
- **TOSA Reference Model:** Apache-2.0
- **TOSA MLIR Translator:** Apache-2.0 with LLVM Exceptions

See individual component directories for detailed license information and third-party project licenses.
