# First model

Convert the MLPerf Tiny keyword-spotting model into a stand-alone C module and
inspect its sources, headers and memory plan. This is a runnable companion to Getting started. It selects
neuralSPOT packaging; the tutorial’s complete firmware path uses Zephyr.

| Field | Value |
| --- | --- |
| Model | kws_ref, MLPerf Tiny keyword spotting, int8 |
| Target | `apollo510_evb` |
| Shows | One conversion, the emitted module tree, and the arena summary the converter prints |
| CI | Conversion and host compilation are declared in the examples CI job |

The model is `audio/mlperf-tiny/kws_ref/model.tflite` from helia-model-zoo:
int8, 53,936 bytes, SHA-256 `aeea4368…bd0ae`, fetched by `run.sh` and checked
against the fixed SHA-256 recorded in the checked-in run script. Model licensing is not established by these hashes; see [Model provenance](https://ambiqai.github.io/helia-aot/examples/).

## Prerequisites

Use a repository checkout with Bash and the environment from [Running examples](https://ambiqai.github.io/helia-aot/examples/): `uv sync --frozen --group ci`, then activate `.venv`. Fetched models require network access, `curl` and `sha256sum` or `shasum`. Run the commands below from this example directory. Conversion runs on the host; it does not execute the emitted firmware.

## Run it

```sh
./run.sh
```

The script fetches the model and its golden fixture from helia-model-zoo,
checks both against the fixed SHA-256 values recorded in the checked-in run script,
and runs the conversion in [config.yaml](https://github.com/AmbiqAI/helia-aot/blob/cf2246a7ad439fa38d57462118e7840e5497a685/examples/first-model/config.yaml). Anything you add on the
command line is passed through to `helia-aot convert`, so

```sh
./run.sh --module.type zephyr --module.path /tmp/zephyr-module
```

emits the same model for a different build system without editing the file.

The model and target match
[Convert your first model](https://ambiqai.github.io/helia-aot/getting-started/convert/),
with neuralSPOT selected here as the output format. The scalar CLI equivalent is:

```sh
helia-aot convert --model.path models/kws_ref.tflite --model.name kws_ref \
  --module.path ./out --module.name kws_ref --module.type neuralspot \
  --platform.name apollo510_evb --test.enabled --test.golden-data models/golden.npz
```

## What to look at

The final result frame names the model, target, output path and arena plan.
Check that conversion exits successfully, writes `out/kws_ref/`, and reports
no unsupported model or memory-planning error. Counts and sizes can change
with compiler/transform versions; preserve the log with the model hash and
configuration instead of treating a captured count as a permanent contract.

Read the arena roles before tuning: scratch slots can be reused within a run;
cold constants are read in place. Target capabilities constrain eligible
implementations but do not prove that every operation uses an optimized kernel.

The module itself is one directory:

```text
out/kws_ref/
  includes-api/   start with aot_model.h
  src/            model, tensor, context, constants and operator sources
  module.mk       the neuralSPOT build fragment
  LICENSE
  README.md
```

`aot_model_init()` and `aot_model_run()` are the minimal application lifecycle.
Check both status values before using outputs. Optional test, callback, arena
binding and hydration interfaces have additional contracts in their generated
headers; per-node wrappers and private context fields are implementation details.

`test.enabled` added `src/aot_test_case.c`, a harness that runs the module
against the golden fixture on target and reports the largest difference per
output. Converting emits it. Running it is a separate step, on hardware or a
simulator.

## Model and golden contract

The pinned fixture has one int8 input `[1, 49, 10, 1]` (490 bytes) and one
int8 output `[1, 12]` (12 bytes). The archive keys are `input_0` and `output_0`.
The run script checks model SHA-256
`aeea436800704fce17b17292e4412630ad856e9d777c044c64ef748a880bd0ae`
and golden SHA-256
`434290baa67ce60cf6e7b0d3f5539acae92d3c0890d9f30636d16b3762402f13`.
Inspect the generated README's I/O tables for quantization parameters; raw
integer bytes must match the model's scale and zero point. Generating the test
harness does not execute it on a board or establish application accuracy.

## Next

- [Memory placement](https://ambiqai.github.io/helia-aot/examples/memory-placement/) for what the arena lines can be
  made to say.
- [Integrate it into your build](https://ambiqai.github.io/helia-aot/getting-started/integrate/)
  for the neuralSPOT, Zephyr, CMake, NSX and CMSIS-Pack packagings.