Configuration

A conversion is described by the configuration model below. Write settings in a YAML file passed to --path; scalar paths also have CLI flags such as --model.path. Structured lists of nested models, such as operator and tensor rules, belong in YAML. Explicit CLI values override matching YAML settings; see the configuration guide for precedence and validation.

The tables are generated from the configuration model. Use the configuration guide for complete examples, precedence and rule matching.

Setting a field

The same two settings, first as a configuration file and then as flags:

model:
  path: model.tflite
module:
  type: neuralspot

helia-aot convert --model.path model.tflite --module.type neuralspot

ConvertArgs

Setting	Type	Default	Constraints	Command line	Description
path	Path	—	—	--path	Path to yaml configuration
model	ModelArgs	the defaults below	—	configuration file only	Model configuration
module	ModuleArgs	the defaults below	—	configuration file only	Module configuration
test	TestArgs	the defaults below	—	configuration file only	Test configuration
transforms	list of TransformSpec	the defaults below	—	--transforms	Transforms configuration
memory	MemoryArgs	the defaults below	—	configuration file only	Memory configuration
platform	PlatformArgs	the defaults below	—	configuration file only	Target platform configuration
operators	list of OperatorRuleset	the defaults below	—	--operators	Operator attributes and optimization knob overrides
documentation	DocumentationArgs	the defaults below	—	configuration file only	Documentation configuration
optimization	OptimizationArgs	the defaults below	—	configuration file only	Optimization goal, approximation gate and knobs
verbose	int	1	≥ 0; ≤ 3	--verbose	Verbosity level
force	bool	false	—	--force / --no-force	Force conversion even if output exists
keep_work_dir	bool	false	—	--keep-work-dir / --no-keep-work-dir	Keep the temporary work directory and log its path
log_file	Path	—	—	--log-file	Optional log file path

ModelArgs

Setting	Type	Default	Constraints	Command line	Description
model.path	Path	model.tflite	—	--model.path	Path to target model file
model.subgraph	int	0	≥ 0	--model.subgraph	Subgraph index
model.type	str	—	—	--model.type	Model type (e.g., tflite, litert)
model.name	str	model	—	--model.name	Model name
model.description	str	—	—	--model.description	Description of the model
model.version	str	v1.0.0	—	--model.version	Model version

ModuleArgs

Setting	Type	Default	Constraints	Command line	Description
module.path	Path	output.zip	—	--module.path	Output path for the generated module. Use a directory for an unpacked module, a ‘.zip’ suffix for a generic zip archive, or a ‘.pack’ suffix for an Open-CMSIS-Pack archive (requires module.type=cmsis_pack).
module.type	ModuleType	neuralspot	one of neuralspot, zephyr, cmake, nsx, cmsis_pack	--module.type	Module type
module.name	str	helia_aot_nn	pattern ^[A-Za-z_][A-Za-z0-9_-]*$	--module.name	Module name
module.prefix	str	aot	pattern ^[A-Za-z_][A-Za-z0-9_]*$	--module.prefix	Prefix added to sources for unique namespace
module.schedule	ScheduleMode	table	one of table, static	--module.schedule	Operator dispatch shape in the generated model: ‘table’ (default) keeps the runtime function-pointer table and per-node callback seam; ‘static’ emits straight-line direct calls (no table, no loop, no indirect dispatch).

TestArgs

Setting	Type	Default	Constraints	Command line	Description
test.enabled	bool	false	—	--test.enabled / --no-test.enabled	Include test case
test.tolerance	float	1	—	--test.tolerance	Test tolerance
test.skip_verification	bool	false	—	--test.skip-verification / --no-test.skip-verification	Skip runtime output verification
test.golden_data	Path	—	—	--test.golden-data	Golden input/output npz file
test.num_iterations	int	1	—	--test.num-iterations	Number of times to run the same stimulus through the model
test.state_feedback	list[tuple[int, int]]	[]	—	--test.state-feedback	(output_index, input_index) pairs copied back between iterations for streaming recurrent-state carry

TransformSpec

Setting	Type	Default	Constraints	Command line	Description
transforms[].name	str	*	—	configuration file only	Name of the transform
transforms[].enabled	bool	true	—	configuration file only	Whether the transform is enabled
transforms[].options	dict[str, float | int | str | bool | list[float | int | str | bool] | dict[str, float | int | str | bool]]	{}	—	configuration file only	Additional options for the transform

MemoryArgs

Setting	Type	Default	Constraints	Command line	Description
memory.planner	MemoryPlannerType	greedy	one of greedy, greedy_by_size, hill_climb	--memory.planner	Memory planner strategy (greedy_by_size and hill_climb are experimental)
memory.planner_options	dict[str, Any]	{}	—	--memory.planner-options	Planner tunables as JSON, validated against the selected planner’s option schema (hill_climb: iterations, seed, max_stall_iterations)
memory.constraints	list of MemoryConstraint	the defaults below	—	--memory.constraints	Memory constraints (ordered by preference)
memory.tensors	list of AttributeRuleset	the defaults below	—	--memory.tensors	Tensor attributes
memory.allocate_arenas	bool	true	—	--memory.allocate-arenas / --no-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.
memory.auto_hydrate_constants	bool	true	—	--memory.auto-hydrate-constants / --no-memory.auto-hydrate-constants	Deprecated — retained for backwards compatibility but no longer changes generated runtime behavior. model_init always invokes hydrate_constants between context_init and the operator init loop. Override the weak hydrate_constants symbol for custom hydration mechanisms (DMA / async pre-stage / model swap).
memory.dump_residency_json	bool	false	—	--memory.dump-residency-json / --no-memory.dump-residency-json	If true, write a machine-readable residency report (<prefix>_residency.json) alongside the emitted module. Mirrors the verbose log summary as JSON for tooling that needs to introspect arena layout, staged-vs-cold residency, and per-tensor placement post-planning.

MemoryConstraint

Setting	Type	Default	Constraints	Command line	Description
memory.constraints[].name	MemoryType	—	one of mram, sram, dtcm, itcm, dram, psram; required	configuration file only	Memory type (e.g., DTCM, ITCM)
memory.constraints[].max_size	int	—	—	configuration file only	Maximum size in bytes, or None for no limit
memory.constraints[].arena_alignment	int	—	—	configuration file only	Optional per-arena alignment floor in bytes. When set, applied to both the arena base symbol and every slot. When None, only the 16-byte implementation floor applies to the base; per-slot alignment is driven by platform / dtype / tensor hints.

AttributeRuleset

Setting	Type	Default	Constraints	Command line	Description
memory.tensors[].type	str	*	—	configuration file only	Entity type (e.g. CONV_2D) or * for all
memory.tensors[].id	str | list[str] | None	—	—	configuration file only	Entity identifier(s)
memory.tensors[].attributes	dict[str, float | int | str | bool]	{}	—	configuration file only	Entity attributes

PlatformArgs

Setting	Type	Default	Constraints	Command line	Description
platform.name	str	apollo510_evb	—	--platform.name	Target platform name
platform.cpu	str	—	—	--platform.cpu	CPU core type (e.g., cortex-m55)
platform.speeds	list[int]	[]	—	--platform.speeds	List of supported clock speeds in MHz
platform.memories	dict[helia_aot.platforms.defines.MemoryType, int]	{}	—	--platform.memories	Memory sizes in bytes
platform.capabilities	list[helia_aot.platforms.defines.SocCapability]	[]	—	--platform.capabilities	List of SoC capabilities
platform.preferred_memory_order	list[helia_aot.platforms.defines.MemoryType]	[]	—	--platform.preferred-memory-order	Preferred memory order for allocations
platform.min_alignment	int	—	—	--platform.min-alignment	Minimum alignment requirement in bytes

OperatorRuleset

Setting	Type	Default	Constraints	Command line	Description
operators[].type	str	*	—	configuration file only	Entity type (e.g. CONV_2D) or * for all
operators[].id	str | list[str] | None	—	—	configuration file only	Entity identifier(s)
operators[].attributes	dict[str, float | int | str | bool]	{}	—	configuration file only	Entity attributes
operators[].optimization	OperatorOptimization	the defaults below	—	configuration file only	Optimization knob overrides for the matched operators

OperatorOptimization

Setting	Type	Default	Constraints	Command line	Description
operators[].optimization.accumulation	Accumulation	—	one of auto, precise, fast	configuration file only	Override of optimization.accumulation
operators[].optimization.kernel	KernelChoice	—	one of auto, specialized, generic	configuration file only	Override of optimization.kernel

DocumentationArgs

Setting	Type	Default	Constraints	Command line	Description
documentation.html	bool	false	—	--documentation.html / --no-documentation.html	Generate html documentation site (experimental).

OptimizationArgs

Setting	Type	Default	Constraints	Command line	Description
optimization.goal	OptimizationGoal	balanced	one of latency, balanced, size, accuracy	--optimization.goal	What auto knob values favor: latency, balanced (today’s defaults), size or accuracy
optimization.allow_approximate	bool	false	—	--optimization.allow-approximate / --no-optimization.allow-approximate	Allow auto knob values that change numerics relative to the knob’s default (e.g. fast accumulation)
optimization.accumulation	Accumulation	auto	one of auto, precise, fast	--optimization.accumulation	FP16 accumulation: precise (standard layout, the library’s default accumulation), fast (packed FP16 weights, one FP16 chain per output) or auto
optimization.kernel	KernelChoice	auto	one of auto, specialized, generic	--optimization.kernel	Int8 convolution and depthwise entry: specialized (shape-specialized ns-cmsis-nn direct entries where they apply), generic (the general entries, fewer kernels linked) or auto; both are exact
optimization.budget	dict[str, float]	—	—	configuration file only	Reserved: constraints for the optimizer, e.g. accuracy_drop or tcm_bytes
optimization.plan	Path	—	—	configuration file only	Reserved: path to a resolved optimization plan to reproduce

A list entry has no flag of its own

Settings written as name[].field belong to entries of a list. A list is given in the configuration file; the command line sets the fields that are not inside one.