heliaAOT

Bring blazing-fast, ultra-compact neural inference to Ambiq’s ultra-low-power SoCs—without a runtime.

CI | Docs | Build Wheel | Release

heliaAOT is an ahead-of-time (AOT) compiler that converts front-end models (e.g., TFLite) into stand-alone C inference modules optimized for Ambiq microcontrollers. By shifting codegen to build-time and eliminating the runtime interpreter, heliaAOT delivers compact, readable C with zero arena-guesswork and no dead code.

✨ Why heliaAOT?

• Smaller binaries – Generate only the code you need. No interpreter, no dead kernels.
• Deterministic memory – Context-level memory planning; stop guessing arena sizes.
• Readable output – Layer-mirrored C files for fast bring-up and debugging.
• Ambiq-tuned – Optimized for Cortex-M (M4/M55/Helium) on Ambiq SoCs.
• Production-ready – Drop into Zephyr/neuralSPOT or your existing build system.

🚀 Quick Start

Option A: Install via pipx

pipx install --python python3.12 helia-aot
helia-aot --help

We recommend pipx because it installs Python apps in isolated, self-contained environments and puts the CLI on your PATH.

Option B: Install via uv

uv tool install --python python3.12 helia-aot
helia-aot --help

Option C: Install via pip

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install helia-aot
helia-aot --help

Option D: Install from source

git clone https://github.com/AmbiqAI/helia-aot.git
cd helia-aot
uv sync
uv run helia-aot --help

🧭 First Conversion

helia-aot convert \
  --model.path ./model.tflite \
  --module.path ./out \
  --module.name my_model_aot

What you get:

out/my_model_aot/
├── LICENSE               # License for the generated module
├── README.md             # Module usage notes
├── includes-api/         # Public C headers
├── src/                  # Operator implementations
└── module.mk

Drop the folder into your firmware tree and build like any other C module.

🛠️ Current CLI

heliaAOT exposes the following commands:

• convert – Convert a TFLite model into a C inference module.

  helia-aot convert --help
  

• list-targets – List every supported target platform name.

  helia-aot list-targets
  

• target-info – Show a target's CPU, clock speeds, memories, and capabilities.

  helia-aot target-info --name apollo330mp_evb
  

  We follow “progressive disclosure of complexity.” The CLI starts simple; advanced flags and expert workflows are documented in the site’s How-to and Reference sections.

📚 Documentation

• Getting Started: the fastest way from model → C module
• How-To: step-by-step recipes for common tasks
• Reference: full list of commands/flags
• Guides: end-to-end projects and best practices
• Benchmarks: performance and size comparisons
• API: for power users who integrate deeper

The docs are written for CLI users first; you don’t need to know (or care) that the tool is implemented in Python.

🔌 Supported Inputs & Targets

Inputs

• LiteRT/TFLite (int8/int16)

Targets

• Ambiq SoCs (Cortex-M4, M55/Helium)
• Integration paths: Zephyr module, neuralSPOT, or make/CMake projects

🧩 What the Generated C Looks Like

• A compact operator library: only kernels required by your model.
• A structured init() / run() style API with clear I/O.
• Compile-time tensor shapes and a fixed memory plan.
• Optional operator callbacks for instrumentation/telemetry.

🧪 Testing & Quality

• Continuous Integration runs linting and unit tests
• Deterministic builds and reproducible outputs where possible
• Example apps and benchmarks in the docs

⚙️ Development (optional)

If you do want to contribute or run from source:

# Using uv (fast Python package manager)
uv sync
uv run helia-aot --help

# Or with pip + virtualenv
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
helia-aot --help

Developer setup

uv sync --group ci        # test + lint dependencies (also the venv ty reads)
git lfs pull              # model fixtures used by the test suite
uv tool install pre-commit
pre-commit install

pre-commit install covers the pre-commit stage (whitespace fixers, gitleaks, ruff, ty, the TODO(#123) marker check). To check the whole tree the way CI does:

pre-commit run --all-files

The ty type check blocks the commit on any error-level diagnostic and runs with ty's default rule severities; a unit test pins the warning count at zero so it cannot creep back. It prints a one-line summary (full report in .pre-commit/ty.log) and resolves imports against .venv, so if you haven't run uv sync yet — or ran a bare uv venv without syncing — it prints a one-line skip with a hint instead. On a venv without tensorflow (Python 3.14, where the ci group does not install it) it allows tensorflow imports to stay unresolved and says so in the summary.

🗺️ Roadmap

The project roadmap and features can be found on the GitHub Projects page.

We prioritize features that keep binaries tiny, predictable, and fast.

💬 Support & Feedback

• Issues / bugs: Create an issue on GitHub
• Feature requests and discussions: Join the conversation

📄 License

heliaAOT generates C modules that include a license header restricting use to Ambiq hardware. See the generated module’s LICENSE.txt for terms and the repository’s LICENSE for tooling.

Ready to dive in? Head over to the Getting Started guide and generate your first module in minutes.