# Compatibility and versioning heliaAOT follows [semantic versioning](https://semver.org/) from 1.0.0. This page says which parts of heliaAOT the version number covers. A part that is not listed under [What a release promises](https://ambiqai.github.io/helia-aot/reference/compatibility/#what-a-release-promises) can change in any release. ## What a release promises Within one major version, each surface below keeps working as its reference page describes it. Most of those pages are rendered from a record exported from the code, named in the last column, and a test fails when a committed record no longer matches what the code exports. Some records are partly written by hand, such as the operator restrictions, and the plan and report rule is written on a page rather than exported. | Surface | What is promised | Described by | | --- | --- | --- | | Command line | Command names, flags, accepted values and [exit codes](https://ambiqai.github.io/helia-aot/reference/compatibility/#exit-codes) | [Command line](https://ambiqai.github.io/helia-aot/reference/cli/) (`cli.json`) | | Configuration file | Keys, accepted values and defaults, and that an unknown key or an invalid attribute value is an error; other `operators[].attributes` keys pass through to the code templates | [Configuration](https://ambiqai.github.io/helia-aot/reference/configuration/) (`config-schema.json`) | | Python API | The symbols listed in the API manifest | [Python API](https://ambiqai.github.io/helia-aot/reference/api/helia_aot/) (`repo_tools/api_manifest.json`) | | Typed errors | The `HeliaAotError` classes and the standard-library type each one also is | [Errors](https://ambiqai.github.io/helia-aot/reference/errors/) (`errors.json`) | | Generated module | File names, `_` symbols, the `init` and `run` signatures and their status codes, and the `cmake`, `zephyr` and `nsx` module types | [Generated module](https://ambiqai.github.io/helia-aot/reference/module/) (`module-layout.json`) | | Residency report | Only that it is written, with a `schema_version`, when `memory.dump_residency_json` is set; its fields and values can change | [Generated module](https://ambiqai.github.io/helia-aot/reference/module/) (`residency-example.json`, `residency-example-placed.json`) | | Plan and report files | The `schema_version` rule for `_plan.json` and `_report.json`, written in the guide | [The plan and the report](https://ambiqai.github.io/helia-aot/guide/options/#the-plan-and-the-report) (`plan-schema.json`, `report-schema.json`) | | Targets | Registered platform names, matched in any case | [Targets](https://ambiqai.github.io/helia-aot/reference/targets/) (`targets.json`) | | Operators | Registered operator names; see [the support matrix](https://ambiqai.github.io/helia-aot/reference/compatibility/#the-support-matrix) | [Operator catalog](https://ambiqai.github.io/helia-aot/reference/operators/) (`operators.json`) | | heliaCORE floor | The repository-wide minimum ns-cmsis-nn release; see [the heliaCORE floor](https://ambiqai.github.io/helia-aot/reference/compatibility/#the-heliacore-floor) | [Version requirements](https://ambiqai.github.io/helia-aot/reference/versions/) (`versions.json`) | ### The support matrix The operator catalog and the target list at the 1.0.0 tag are the frozen support matrix for 1.x. Minor releases can add operators, dtypes and targets; only a major release removes one. An operator's dtypes and restrictions in the catalog describe what it accepts, and some are transcribed by hand. A minor or patch release can tighten an operator's checks to reject a model its kernels cannot run correctly. That is a fix, not a breaking change: such a model never produced correct output. ## Exit codes The exit codes and their meanings are part of the promise. They are listed on the [command line reference](https://ambiqai.github.io/helia-aot/reference/cli/#exit-codes), which renders them from the command line's own definition in `cli.json`, and which says which failures fall under each code. One condition applies: an interrupt before conversion starts exits 130 only with typer 0.23 or newer, which `pyproject.toml` does not require. ## What is not promised These can change in any release, including a patch release: - **The code a module is built from.** Kernel choice per layer, scratch sizes, arena layout and offsets, and the bytes of the generated C. A new release can emit different C for the same model and configuration. - **Numerical results.** A different kernel, rounding mode or approximation can change the output values a model produces. - **Performance.** Latency, image size and memory use. The [benchmarks](https://ambiqai.github.io/helia-aot/guide/benchmarks/) are dated records, not promises. - **Report contents.** The figures and hints in `_report.json`. The plan records the choices. - **The floor of a given model.** See [the heliaCORE floor](https://ambiqai.github.io/helia-aot/reference/compatibility/#the-heliacore-floor). - **Text meant for people.** Error messages and hints, help text, console and log output. Match on the error class and the exit code, not on the wording. - **CMSIS-Pack output**, which is for evaluation until its packs pass full `packchk` validation. See [Firmware integration](https://ambiqai.github.io/helia-aot/getting-started/integrate/#choose-your-build-environment). - **Experimental settings.** Float operators, the offline HTML site (`documentation.html`), and any setting or value the [configuration reference](https://ambiqai.github.io/helia-aot/reference/configuration/) marks experimental. - **Python names outside the API manifest**, including the lower-level helpers the [custom operator](https://ambiqai.github.io/helia-aot/guide/custom-operators/) starter uses. - **Hosts other than Linux.** See [Supported hosts](https://ambiqai.github.io/helia-aot/reference/compatibility/#supported-hosts). ## How the version number changes - A **major** release can make a breaking change to a promised surface: remove or rename something, change a default, change what a value means, or raise the repository-wide heliaCORE floor. - A **minor** release adds to a surface: a command, flag, setting, value, operator, target, error class or optional file field. - A **patch** release fixes defects and changes nothing promised, except to make it work as documented. A deprecated setting or flag is still accepted, with a warning, for at least one minor release, and is removed only in a major release. Deprecated settings are marked in the [configuration reference](https://ambiqai.github.io/helia-aot/reference/configuration/). The release notes list each deprecation and each breaking change. ## The heliaCORE floor A generated module calls heliaCORE, Ambiq's neural-network kernel library, which is released as the [ns-cmsis-nn](https://github.com/AmbiqAI/ns-cmsis-nn/releases) package. Each module needs an ns-cmsis-nn release at or above its own floor. The module enforces it with a `#error` in `_common.h`, records it as `generator.cmsis_nn_required` in `_plan.json` and in its README, and a CMSIS-Pack names it as its dependency. Upstream Arm CMSIS-NN is not supported. The repository-wide floor, listed on [Version requirements](https://ambiqai.github.io/helia-aot/reference/versions/), is the lowest any module needs, and it changes only in a major release. A module's own floor can be higher, because the kernels chosen for its layers can need a newer release. Kernel choice is not promised, so the floor a given model needs can rise in a minor release. Read it from the module, not from the operator catalog, whose floor column covers only the float path. ## Supported hosts heliaAOT runs on Python 3.11 to 3.14. Continuous integration runs the test suite on Linux, on Python 3.11 and 3.14. The package metadata says `Operating System :: OS Independent`, but Linux is the only operating system the tests run on: each release installs the wheel and runs `helia-aot --help` on macOS and Windows, and builds standalone binaries for all three, and neither is tested beyond that. The modules heliaAOT generates are licensed for Ambiq CPUs only; see [Support, licence and contributing](https://ambiqai.github.io/helia-aot/reference/support/#licence). Which compilers and build systems have been used to build them is on [Toolchains and build environments](https://ambiqai.github.io/helia-aot/guide/toolchains/). ## Changes from 0.x - The legacy `neuralspot` module type was removed in 1.0; use `cmake` (the new default), `zephyr` or `nsx`. With it, `_platform.h` no longer maps `_PRINTF` to `ns_lp_printf` or the `_PUT_IN_*` hooks to neuralSPOT's sections, and `_PUT_CODE_IN_ITCM` is empty, so operators with `code_placement: ITCM` stay in the default code section. Define the hooks your application needs; without them the arenas and code follow the linker's default placement and logging is silent. - `memory.planner` defaults to `hill_climb` instead of `greedy`. Its scratch arenas are the same size or smaller than `greedy`'s in every memory when `greedy`'s plan fits, but tensor offsets and the memory of an individual tensor can change. Set `memory.planner: greedy` to keep the previous layout. - An unknown key in a nested block, a list entry or `memory.tensors[].attributes` is an error that names the nearest valid key. 0.x dropped such keys, with a warning in its later releases; unknown top-level keys were already rejected. See [When a key is wrong](https://ambiqai.github.io/helia-aot/guide/configuring/#when-a-key-is-wrong). - A `TRANSPOSE_CONV` with `SAME` padding whose input height or width is not divisible by its stride, such as a Keras `Conv2DTranspose` decoder, produced output shifted by one pixel in 0.x. From 1.0 it follows LiteRT, and a declared output shape the operators do not produce is a typed error. - Conversion applies LiteRT's dtype, scale and quantization rules, so a model that breaks one is a typed error with a hint where 0.x gave a traceback, wrong output or code that did not compile. Platform and configuration-value errors that do not depend on the model exit 2 (see [When a key is wrong](https://ambiqai.github.io/helia-aot/guide/configuring/#when-a-key-is-wrong)), and the public I/O tables report scale 1 and zero point 0 for every tensor but an int8, uint8 or int16 one with a scale. - Golden data must match each tensor's element count and dtype; a mismatch or an archive that cannot be loaded raises `GoldenDataError` and exits 2. Attribute values are checked when the configuration loads, and a `.zip` export appears at the output path only when it is complete.