Metadata-Version: 2.4
Name: helia-aot
Version: 0.16.0
Summary: An ahead-of-time nn compiler for Ambiq SoCs.
Author-email: Ambiq AI <support.aitg@ambiq.com>
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: pydantic>=2.6.1
Requires-Dist: requests>=2.31.0
Requires-Dist: tqdm>=4.66.4
Requires-Dist: argdantic[all]>=1.3.3
Requires-Dist: numpy>=2.0.0
Requires-Dist: flatbuffers>=23.5.26
Requires-Dist: ai-edge-litert>=2.1.2
Requires-Dist: rich>=14.0.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: mkdocs>=1.6.0
Requires-Dist: mkdocs-material>=9.5.28
Requires-Dist: pymdown-extensions>=10.14.3
Dynamic: license-file

# heliaAOT

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

[![CI](https://github.com/AmbiqAI/helia-aot/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/AmbiqAI/helia-aot/actions/workflows/ci.yml)
[![Docs](https://github.com/AmbiqAI/helia-aot/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/AmbiqAI/helia-aot/actions/workflows/docs.yml)
[![Build Wheel](https://github.com/AmbiqAI/helia-aot/actions/workflows/build-wheel.yml/badge.svg?branch=main)](https://github.com/AmbiqAI/helia-aot/actions/workflows/build-wheel.yml)
[![Release](https://github.com/AmbiqAI/helia-aot/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/AmbiqAI/helia-aot/actions/workflows/release.yml)

heliaAOT is an ahead-of-time (AOT) compiler that converts front-end models (e.g., TFLite/ONNX) 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: Download a standalone CLI

Prebuilt binaries (no Python required):

- macOS: [helia-aot](https://github.com/AmbiqAI/helia-aot/releases)
- Linux: [helia-aot](https://github.com/AmbiqAI/helia-aot/releases)
- Windows: [helia-aot.exe](https://github.com/AmbiqAI/helia-aot/releases)

> See the **Releases** page for downloads and checksums.

Run:

```bash
./helia-aot --help
```

### Option B: Install via pipx

```bash
pipx install --python python3.12 "git+https://github.com/AmbiqAI/helia-aot.git@main"
helia-aot --help
```

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

### Option C: Install from source

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

---

## 🧭 First Conversion

```bash
helia-aot convert \
  --model.path ./models/ad01_int8.tflite \
  --module.path ./out \
  --module.name ad01_aot
```

**What you get:**

```bash
out/ad01_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 currently exposes a single primary command:

- **convert** – Convert a TFLite/ONNX model into a C inference module.

  ```bash
  helia-aot convert --help
  ```

  > We follow “progressive disclosure of complexity.” The CLI starts simple; advanced flags and expert workflows are documented in the site’s [How-to](https://ambiqai.github.io/helia-aot/how-to/) and [Reference](https://ambiqai.github.io/helia-aot/reference/) sections.


---

## 📚 Documentation

- [Getting Started](https://ambiqai.github.io/helia-aot/usage/): the fastest way from model → C module
- [How-To](https://ambiqai.github.io/helia-aot/how-to/): step-by-step recipes for common tasks
- [Reference](https://ambiqai.github.io/helia-aot/reference/): full list of commands/flags
- [Guides](https://ambiqai.github.io/helia-aot/guides/): end-to-end projects and best practices
- [Benchmarks](https://ambiqai.github.io/helia-aot/benchmarks/): performance and size comparisons
- [API](https://ambiqai.github.io/helia-aot/api/helia_aot/): 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:

```bash
# 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
```

See CONTRIBUTING.md for coding standards, testing, and PR guidelines.

---

## 🗺️ Roadmap

The project roadmap and features can be found on the [GitHub Projects](https://github.com/orgs/AmbiqAI/projects/14) page.

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

---

## 💬 Support & Feedback

- [Issues / bugs](https://github.com/AmbiqAI/helia-aot/issues): Create an issue on GitHub
- [Feature requests and discussions](https://github.com/AmbiqAI/helia-aot/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](./LICENSE.md) for tooling.

---

> **Ready to dive in?**
> Head over to the [Getting Started](https://ambiqai.github.io/helia-aot/usage/) guide and generate your first module in minutes.
