# 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](https://ambiqai.github.io/helia-aot/guide/configuring/) for complete examples, precedence and rule matching.

## Setting a field

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

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

```sh
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](https://ambiqai.github.io/helia-aot/reference/configuration/#modelargs) | the defaults below | — | configuration file only | Model configuration |
| `module` | [ModuleArgs](https://ambiqai.github.io/helia-aot/reference/configuration/#moduleargs) | the defaults below | — | configuration file only | Module configuration |
| `test` | [TestArgs](https://ambiqai.github.io/helia-aot/reference/configuration/#testargs) | the defaults below | — | configuration file only | Test configuration |
| `transforms` | list of [TransformSpec](https://ambiqai.github.io/helia-aot/reference/configuration/#transformspec) | the defaults below | — | `--transforms` | Transforms configuration |
| `memory` | [MemoryArgs](https://ambiqai.github.io/helia-aot/reference/configuration/#memoryargs) | the defaults below | — | configuration file only | Memory configuration |
| `platform` | [PlatformArgs](https://ambiqai.github.io/helia-aot/reference/configuration/#platformargs) | the defaults below | — | configuration file only | Target platform configuration |
| `operators` | list of [OperatorRuleset](https://ambiqai.github.io/helia-aot/reference/configuration/#operatorruleset) | the defaults below | — | `--operators` | Operator attributes and optimization knob overrides |
| `documentation` | [DocumentationArgs](https://ambiqai.github.io/helia-aot/reference/configuration/#documentationargs) | the defaults below | — | configuration file only | Documentation configuration |
| `optimization` | [OptimizationArgs](https://ambiqai.github.io/helia-aot/reference/configuration/#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](https://ambiqai.github.io/helia-aot/reference/configuration/#memoryconstraint) | the defaults below | — | `--memory.constraints` | Memory constraints (ordered by preference) |
| `memory.tensors` | list of [AttributeRuleset](https://ambiqai.github.io/helia-aot/reference/configuration/#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](https://ambiqai.github.io/helia-aot/reference/configuration/#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 |

:::note[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.
:::