README.md

<!--
    SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates <open-source-office@arm.com>

    SPDX-License-Identifier: Apache-2.0
-->

# TOSA converter for TFLite

A tool to legalize TFLite FlatBuffer to TOSA MLIR Bytecode or Text.

## Requirements

Before you build or run the converter, ensure you have the following tools installed and on your PATH.

### Linux (Ubuntu)

| Tool   | Purpose         | Minimum Version  |
|--------|-----------------|------------------|
| Bazel  | build           | v7.4.1 or later  |
| Python | runtime & build | v3.9 or later    |
| Clang  | build           | v17 or later     |

### Windows (x86_64)

| Tool                                                     | Purpose         | Version                               |
|----------------------------------------------------------|-----------------|---------------------------------------|
| Bazelisk                                                 | build           | Latest                                |
| Python                                                   | runtime & build | ≥3.9                                  |
| LLVM (Clang-CL)                                          | build           | 20.1.0                                |
|Visual Studio 2022 Professional (C++ Desktop Dev Tools)  | build & debug   | 17.11.5                               |
| MSYS2                                                    | shell & tooling | 3.6.3-2 / Pacman 20.1.0 with bash.exe |

## Python wheel creation

To build the Python wheel Clang is required, the wheel can then be built using:

```console
pip install build
python -m build --wheel
```

The wheel should now be in the `dist` directory.


## Usage

### Python API

```python
from tosa_converter_for_tflite import tflite_flatbuffer_to_tosa_mlir, TosaConverterOutputFormat

# default (bytecode) output
tflite_flatbuffer_to_tosa_mlir("model_input.tflite", "model_output.tosa.mlirbc")

# textual MLIR output
tflite_flatbuffer_to_tosa_mlir(
    "model_input.tflite",
    "model_output.mlir",
    TosaConverterOutputFormat.Text
)
```

### Command-line Interface (CLI)

The `tosa-converter-for-tflite` CLI provides a simple way to convert `.tflite` models
into TOSA MLIR(bytecode or text). It supports both file-based and stream-based workflows
for easy integration into toolchains or pipelines.

### Usage Examples

**Convert a `.tflite` file to a TOSA bytecode file(default):**

```bash
tosa-converter-for-tflite model.tflite --bytecode -o out.tosa.mlirbc
```

**Read the model from file and write textual TOSA MLIR to file**

```bash
tosa-converter-for-tflite model.tflite --text -o out.mlir
```

**Read the model from a file and write textual TOSA MLIR to stdout**

```bash
tosa-converter-for-tflite model.tflite --text
```

**Stream the model from stdin and write bytecode to file**
```bash
cat model.tflite | tosa-converter-for-tflite --bytecode -o out.tosa.mlirbc
```

**Fully stream the model from stdin and write textual MLIR to stdout**
```bash
cat model.tflite | tosa-converter-for-tflite --text
```

## Supported Platforms

This tool supports Linux(r) and Windows(r) on x86_64 architectures.

## Versioning

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

- **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.

# License

TOSA Converter for TFLite is distributed under the Apache 2.0 License.

# Trademarks and Copyrights

* Bazel(tm) is a trademark of Google(r) LLC.
* Git(tm) is a trademark of Software Freedom Conservancy.
* Linux(r) is the registered trademark of Linus Torvalds in the U.S. and elsewhere.
* Windows(r) is a registered trademark of Microsoft Corporation.
* Python(r) is a registered trademark of the PSF.
* Ubuntu(r) is a registered trademark of Canonical.
* Tensorflow(tm) is a trademark of Google(r) LLC.