Compatibility and versioning

heliaAOT follows semantic versioning 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 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	Command line (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 (config-schema.json)
Python API	The symbols listed in the API manifest	Python API (repo_tools/api_manifest.json)
Typed errors	The HeliaAotError classes and the standard-library type each one also is	Errors (errors.json)
Generated module	File names, <prefix>_ symbols, the init and run signatures and their status codes, and the cmake, zephyr and nsx module types	Generated 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 (residency-example.json, residency-example-placed.json)
Plan and report files	The schema_version rule for <prefix>_plan.json and <prefix>_report.json, written in the guide	The plan and the report (plan-schema.json, report-schema.json)
Targets	Registered platform names, matched in any case	Targets (targets.json)
Operators	Registered operator names; see the support matrix	Operator catalog (operators.json)
heliaCORE floor	The repository-wide minimum ns-cmsis-nn release; see the heliaCORE floor	Version requirements (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, 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 are dated records, not promises.
• Report contents. The figures and hints in <prefix>_report.json. The plan records the choices.
• The floor of a given model. See 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.
• Experimental settings. Float operators, the offline HTML site (documentation.html), and any setting or value the configuration reference marks experimental.
• Python names outside the API manifest, including the lower-level helpers the custom operator starter uses.
• Hosts other than Linux. See 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. 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 package. Each module needs an ns-cmsis-nn release at or above its own floor. The module enforces it with a #error in <prefix>_common.h, records it as generator.cmsis_nn_required in <prefix>_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, 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. Which compilers and build systems have been used to build them is on Toolchains and build environments.

Changes from 0.x

• The legacy neuralspot module type was removed in 1.0; use cmake (the new default), zephyr or nsx. With it, <prefix>_platform.h no longer maps <PREFIX>_PRINTF to ns_lp_printf or the <PREFIX>_PUT_IN_* hooks to neuralSPOT’s sections, and <PREFIX>_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.
• 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), 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.