# Examples

Start with a model, then explore memory, precision, custom operators or hardware profiling. Every example includes a walkthrough, configuration and runnable script.

## Choose an example

### Start with a model

- [First model](https://ambiqai.github.io/helia-aot/examples/first-model/): One conversion, the emitted module tree, and the arena summary the converter prints

### Configure and tune

- [Memory placement](https://ambiqai.github.io/helia-aot/examples/memory-placement/): Per-role placement rules, staged constants, caller-supplied arenas, and residency-report comparisons
- [Static schedule](https://ambiqai.github.io/helia-aot/examples/static-schedule/): module.schedule, generated dispatch code and callback availability
- [Float and FP16](https://ambiqai.github.io/helia-aot/examples/float-fp16/): Float kernel selection, the FP16 platform gate, and the ns-cmsis-nn build switches a float module needs

### State and extension

- [Recurrent state](https://ambiqai.github.io/helia-aot/examples/recurrent-state/): LiteRT variable tensors as persistent arenas, and what test.state_feedback is for
- [Custom operator](https://ambiqai.github.io/helia-aot/examples/custom-operator/): RegistryContext, a LiteRT parser, an AotOperator subclass, and the Python-only path a custom operator takes

### Hardware recipes

- [Ethos-U](https://ambiqai.github.io/helia-aot/examples/ethos-u/): The Ethos-U operator, the driver dependency, and the platform gate
- [Profile with hpx](https://ambiqai.github.io/helia-aot/examples/profile-with-hpx/): The two-config comparison recipe and how to read it

## Before you start

These examples require access to the private heliaAOT repository. A package-only installation does not include the example checkout.

Use a repository checkout with Bash and Python 3.11 or newer. From the repository root, prepare and activate the project environment:

```sh
uv sync --frozen --group ci
source .venv/bin/activate
```

Fetched-model examples also need `curl` and `sha256sum` or `shasum`. An isolated CLI installation does not include the Python dependencies used by the model-building scripts.

Ethos-U needs a Vela-compiled model. Profiling needs a supported board and the profiler toolchain. Check the prerequisites on each example page before running it.

## Run an example

From the repository root, after activating the environment:

```sh
cd examples/first-model
./run.sh
```

The script fetches or builds its model and writes the converted module under `out/`. Read the example page before selecting another configuration or building the generated firmware.

## Host conversion and compile checks

Six examples have CI conversion and host-compilation checks; these do not establish on-device numerical or timing qualification. Browse the [source examples](https://github.com/AmbiqAI/helia-aot/tree/cf2246a7ad439fa38d57462118e7840e5497a685/examples) for their READMEs and scripts. No model binaries are committed.

The canonical [example overview](https://github.com/AmbiqAI/helia-aot/blob/cf2246a7ad439fa38d57462118e7840e5497a685/examples/README.md#what-ci-runs) documents `examples/check.sh` and its `HELIA_CMSIS_NN_SOURCE_DIR` dependency. This compiles individual translation units; it does not link or run target inference.

## Model provenance

The examples that use a model from
[helia-model-zoo](https://github.com/AmbiqAI/helia-model-zoo) use
`audio/mlperf-tiny/kws_ref`. The checked-in run scripts define the expected
model and golden SHA-256 values. Consult the upstream model card for its
provenance; this example does not establish the current contents of the entire
zoo or its manifest.

The downloader uses fixed SHA-256 values but fetches from the zoo's `main`
branch. A changed artifact fails the hash check; do not replace the expected
hash just to make a download succeed. Record the model hash and the source
revision with your conversion.

These examples do not establish redistribution rights for the downloaded
model. Check the upstream model card and applicable terms for your use; a
model-family name or this repository's software licence does not establish
the model's licence. The synthetic `float-fp16`, `custom-operator` and
`recurrent-state` recipes build small fixtures locally and make no claim about
what other models the current zoo contains.