[convert] command

The convert command emits a standalone C inference module—a set of portable .c/.h files implementing your model’s operators as optimized Ambiq-tuned kernels.

Usage

helia-aot convert [OPTIONS]

usage: helia-aot convert [-h] [--path PATH] [--model.path PATH] [--model.subgraph INT] [--model.type TEXT] [--model.name TEXT]
                          [--model.description TEXT] [--model.version TEXT] [--module.path PATH] [--module.type [neuralspot|zephyr|cmake|nsx|cmsis_pack]]
                          [--module.name TEXT] [--module.prefix TEXT] [--test.enabled | --no-test.enabled] [--test.tolerance TEXT]
                          [--transforms [TEXT ...]] [--memory.planner [greedy]] [--memory.constraints TEXT] [--memory.tensors [TEXT ...]]
                          [--memory.allocate-arenas | --no-memory.allocate-arenas]
                          [--memory.auto-hydrate-constants | --no-memory.auto-hydrate-constants]
                          [--memory.dump-residency-json | --no-memory.dump-residency-json]
                          [--platform.name TEXT] [--operators [TEXT ...]] [--verbose INT]
                          [--force | --no-force] [--log-file TEXT]

options:
  -h, --help            show this help message and exit
  --path PATH           Path to yaml configuration
  --model.path PATH     Path to target model file (default: model.tflite)
  --model.subgraph INT  Subgraph index (default: 0)
  --model.type TEXT     Model type (e.g., tflite, litert)
  --model.name TEXT     Model name (default: model)
  --model.description TEXT
                        Description of the model
  --model.version TEXT  Model version (default: v1.0.0)
  --module.path PATH    Base path for output module. Can also be a zip file.
  --module.type [neuralspot|zephyr|cmake|nsx|cmsis_pack]
                        Module type (default: neuralspot)
  --module.name TEXT    Module name (default: helia_aot_nn)
  --module.prefix TEXT  Prefix added to sources for unique namespace (default: aot)
  --test.enabled        Include test case (default: False)
  --no-test.enabled
  --test.tolerance TEXT
                        Test tolerance (default: 1.0)
  --transforms [TEXT ...]
                        Transforms configuration
  --memory.planner [greedy]
                        Memory planner strategy (default: greedy)
  --memory.constraints TEXT
                        Memory constraints (ordered by preference)
  --memory.tensors [TEXT ...]
                        Tensor attributes
  --memory.allocate-arenas
                        If true, the module will use internal, statically allocated arenas. If false, the caller must bind every region via
                        <prefix>_bind_arena() / <prefix>_bind_arenas() before model_init. (default: True)
  --no-memory.allocate-arenas
  --memory.auto-hydrate-constants
                        If true (default), context_init auto-invokes hydrate_constants for staged-constant arenas. Set false for callers that
                        drive hydration themselves (DMA / async pre-stage).
  --no-memory.auto-hydrate-constants
  --memory.dump-residency-json
                        If true, write a machine-readable residency report (<prefix>_residency.json) alongside the emitted module. (default: False)
  --no-memory.dump-residency-json
  --platform.name TEXT  Target platform name (default: apollo510_evb)
  --operators [TEXT ...]
                        Operator attributes
  --verbose INT         Verbosity level (default: 1)
  --force               Force conversion even if output exists (default: False)
  --no-force
  --log-file TEXT       Optional log file path

Examples

Basic Conversion

helia-aot convert \
  --model.path ad01-int8.tflite \
  --module.path ./out \
  --test.enabled

Advanced Conversion

helia-aot convert \
    --model.path ad01-int8.tflite \
    --model.subgraph 0 \
    --module.path ./out \
    --module.name ad01-int8 \
    --module.type zephyr \
    --module.prefix ad01 \
    --memory.planner greedy \
    --test.enabled \
    --verbose 1

Advanced Conversion with YAML

# Put the options in a YAML configuration
cat <<EOF > ad01-int8.yaml
model:
    path: ad01-int8.tflite
    subgraph: 0
module:
    path: ./out
    name: ad01-int8
    type: zephyr
    prefix: ad01
memory:
    planner: greedy
test:
    enabled: true
verbose: 1
EOF

# Run the conversion via yaml configuration
helia-aot convert --path ad01-int8.yaml --verbose 2

Available Arguments

The following arguments are available for the convert command. The default values are shown in the table below.

Note

These are top-level flags. For nested fields, use dotted notation to scope their local flags (e.g., --model.path, --module.type, --memory.planner).

ConvertArgs

Flag	Type	Default	Description
`model`	ModelArgs	`ModelArgs`	Model configuration.
`module`	ModuleArgs	`ModuleArgs`	Module configuration.
`test`	TestArgs	`TestArgs`	Test configuration.
`transforms`	list[TransformSpec]	`[]`	Transforms configuration.
`memory`	MemoryArgs	`MemoryArgs`	Memory configuration.
`platform`	PlatformArgs	`PlatformArgs`	Target platform configuration.
`operators`	list[AttributeRuleset]	`[]`	Operator attributes.
`documentation`	DocumentationArgs	`DocumentationArgs`	Documentation configuration.
`verbose`	`int (0–3)`	`1`	Verbosity level.
`force`	`bool`	`False`	Force conversion even if output exists.
`log_file`	`Path`	`None`	Optional log file path.

ModelArgs

Flag	Type	Default	Description
`path`	`Path`	`model.tflite`	Path to target model file.
`subgraph`	`int`	`0`	Subgraph index.
`type`	`str`	`None`	Model type (e.g., `tflite`, `litert`). If not set, inferred by file extension.
`name`	`str`	`model`	Optional model name.
`description`	`str`	`None`	Optional description of the model.
`version`	`str`	`v1.0.0`	Optional model version.

ModuleArgs

Flag	Type	Default	Description
`path`	`Path`	`output.zip`	Base path for output module (can also be a zip file).
`type`	`ModuleType`	`neuralspot`	Module type (e.g., `neuralspot`, `zephyr`, `cmake`, `nsx`).
`name`	`str`	`helia_aot_nn`	Module name (valid C identifier).
`prefix`	`str`	`aot`	Prefix added to sources for unique namespace (valid C identifier).

TestArgs

Flag	Type	Default	Description
`enabled`	`bool`	`False`	Include test case.
`tolerance`	`float/int`	`1.0`	Test tolerance.

MemoryArgs

Flag	Type	Default	Description
`planner`	`MemoryPlannerType`	`greedy`	Memory planner strategy.
`constraints`	`list[MemoryConstraint]`	`None`	Memory constraints (ordered by preference).
`tensors`	`list[AttributeRuleset]`	`[]`	Tensor attributes.
`allocate_arenas`	`bool`	`True`	If true, the module declares its own arena buffers. If false, the caller must bind every region with `<prefix>_bind_arena()` / `<prefix>_bind_arenas()` before `<prefix>_model_init`; `<prefix>_context_init` returns non-zero when any region is unbound.
`auto_hydrate_constants`	`bool`	`True`	Deprecated — retained for backwards compatibility but no longer changes emitted runtime behavior. `<prefix>_model_init` always invokes `<prefix>_hydrate_constants` between `<prefix>_context_init` and the operator init loop, so kernels that read constants in their `_init` hook always observe hydrated arenas. Override the weak `<prefix>_hydrate_constants` symbol for DMA / async pre-stage / model-swap.
`dump_residency_json`	`bool`	`False`	If true, write a machine-readable residency report `<prefix>_residency.json` alongside the emitted module. Mirrors the `--verbose 2` log summary as JSON for tooling that introspects arena layout, staged-vs-cold residency, and per-tensor placement.

Tensor backing model

All tensors — scratch, persistent (resource-variable), and constant (weight) — are backed by per-memory arenas in the generated C module. There are no per-tensor static symbols. Each tensor descriptor carries (region, offset, size) resolved at runtime against ctx->arena_buffers[region].

Persistents zero-init via memset() in context_init (caller- supplied arena bytes are not BSS-zeroed). Constants are cold when their source memory equals their runtime memory (kernels read in place); they are staged when those memories differ — a contiguous source blob <prefix>_arena_const_<mem>__source[] lives in cold storage and the writable runtime arena <prefix>_arena_const_<mem> is hydrated by the caller before model_run.

Routing is per-tensor via the constant_destination_memory: attribute on tensor rules. See Tensor attributes for the full description, the hydration contract, and the caller-supplied arena wiring example.

PlatformArgs

Flag	Type	Default	Description
`name`	`str`	`apollo510_evb`	Target platform name.

DocumentationArgs

Flag	Type	Default	Description
`html`	`bool`	`False`	Generate html documentation site (experimental).

AttributeRuleset

Used in lists like operators[] or memory.tensors[].

Flag	Type	Default	Description
`type`	`str`	`*`	Entity type (e.g., `CONV_2D`) or `*` for all.
`id`	`str, list[str], None`	`None`	Entity identifier(s).
`attributes`	`dict[str, BasicType]`	`{}`	Key-value map of entity attributes.

TransformSpec

Used in lists like transforms[].

Flag	Type	Default	Description
`name`	`str`	`*`	Name of the transform (`*` matches all).
`enabled`	`bool`	`True`	Whether the transform is enabled.
`options`	`dict[str, NestedType]`	`{}`	Additional transform options.