[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

helios-aot convert [OPTIONS]

usage: helios-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]]
                          [--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] [--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, onnx, etc.)
  --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]
                        Module type (default: neuralspot)
  --module.name TEXT    Module name (default: helios_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 user must populate arena_buffers and
                        arena_sizes before init. (default: True)
  --no-memory.allocate-arenas
  --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

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

Advanced Conversion

helios-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
helios-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`, `onnx`, etc.). 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`).
`name`	`str`	`helios_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 uses internal, statically allocated arenas. If false, the user must populate `arena_buffers` and `arena_sizes` before init.

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.