# helia_aot.optimization.schema

The optimization plan and report files, as typed models with JSON schemas.

``<prefix>_plan.json`` is normative: the resolved choice of every knob for
every operator, what was requested and by which rule, the choices that are not
knobs yet, and the identity of the model and target the plan belongs to. It is
what an optimizer rewrites and what heliaAOT will reproduce.

``<prefix>_report.json`` is non-normative: MACs, alternatives and whether they
apply, measurements, constant placement facts and the hints the results print.
Its content may change between releases, and a plan reader ignores it.

Versioning: both files carry ``schema_version``. Adding an optional field, a
knob, a knob value or an enum member keeps the version; renaming or removing a
field, or changing what a field means, bumps it.

Knob names and each knob's values come from the registry, ``KNOBS``: the
models reject any other, and the exported JSON schemas list them per knob. The
exported schemas therefore belong to the heliaAOT release that produced a file
(``generator.helia_aot``); a consumer validates against that release's schema
and does not pin one across releases.

Some members and fields are reserved and never written today: ``plan`` as a
knob source, ``resolved_by`` and ``set_by`` (a choice taken from an input
plan), ``auto_heuristic`` as ``resolved_by`` (``auto`` consulting the operator
or target rather than the goal table), model-level ``optimization.knobs`` and
per-tensor ``tensors``.

Copyright 2025 Ambiq. All Rights Reserved.

## helia_aot.optimization.schema.RuleRef

`class` · `python`

```python
RuleRef()
```

The ``operators[]`` rule that set a knob.

Source: `helia_aot/optimization/schema.py:108`

### helia_aot.optimization.schema.RuleRef.index

`attribute` · `python`

```python
index: int = Field(..., description='Position of the rule in operators[]')
```

Source: `helia_aot/optimization/schema.py:111`

### helia_aot.optimization.schema.RuleRef.type

`attribute` · `python`

```python
type: str = Field(..., description="The rule's type")
```

Source: `helia_aot/optimization/schema.py:112`

### helia_aot.optimization.schema.RuleRef.id

`attribute` · `python`

```python
id: str | list[str] | None = Field(None, description="The rule's id")
```

Source: `helia_aot/optimization/schema.py:113`

## helia_aot.optimization.schema.KnobSource

`class` · `python`

```python
KnobSource()
```

Who asked for a knob's value; ``rule`` is set exactly when ``kind`` is ``operator``.

Source: `helia_aot/optimization/schema.py:122`

### helia_aot.optimization.schema.KnobSource.model_config

`attribute` · `python`

```python
model_config = ConfigDict(extra='forbid', json_schema_extra=_rule_exactly_for_operator)
```

Source: `helia_aot/optimization/schema.py:125`

### helia_aot.optimization.schema.KnobSource.kind

`attribute` · `python`

```python
kind: Literal['operator', 'model', 'default', 'plan'] = Field(..., description='An operators[] rule, the model-wide optimization section, or neither; plan (an input plan) is reserved')
```

Source: `helia_aot/optimization/schema.py:127`

### helia_aot.optimization.schema.KnobSource.rule

`attribute` · `python`

```python
rule: RuleRef | None = Field(None, description='The operators[] rule, when kind is operator')
```

Source: `helia_aot/optimization/schema.py:133`

## helia_aot.optimization.schema.KnobChoice

`class` · `python`

```python
KnobChoice()
```

The resolved value of one knob for one operator.

``resolved_by`` agrees with ``requested``: ``explicit`` means a value was
asked for and used as given (``value`` equals ``requested``); ``auto_table``
and ``auto_heuristic`` mean ``requested`` is ``auto``.

Source: `helia_aot/optimization/schema.py:155`

### helia_aot.optimization.schema.KnobChoice.model_config

`attribute` · `python`

```python
model_config = ConfigDict(extra='forbid', json_schema_extra=_provenance_is_consistent)
```

Source: `helia_aot/optimization/schema.py:163`

### helia_aot.optimization.schema.KnobChoice.value

`attribute` · `python`

```python
value: str = Field(..., description='The value used')
```

Source: `helia_aot/optimization/schema.py:165`

### helia_aot.optimization.schema.KnobChoice.requested

`attribute` · `python`

```python
requested: str = Field(..., description='The value asked for, possibly auto')
```

Source: `helia_aot/optimization/schema.py:166`

### helia_aot.optimization.schema.KnobChoice.resolved_by

`attribute` · `python`

```python
resolved_by: Literal['explicit', 'auto_table', 'auto_heuristic', 'plan'] = Field(..., description='explicit when a value was asked for; auto_table when auto chose it from the goal; auto_heuristic and plan are reserved')
```

Source: `helia_aot/optimization/schema.py:167`

### helia_aot.optimization.schema.KnobChoice.source

`attribute` · `python`

```python
source: KnobSource
```

Source: `helia_aot/optimization/schema.py:174`

### helia_aot.optimization.schema.KnobChoice.approximate

`attribute` · `python`

```python
approximate: bool = Field(..., description="Whether the value changes numerics relative to the knob's default where it applies")
```

Source: `helia_aot/optimization/schema.py:175`

## helia_aot.optimization.schema.PlanOperator

`class` · `python`

```python
PlanOperator()
```

One operator's choices.

Source: `helia_aot/optimization/schema.py:197`

### helia_aot.optimization.schema.PlanOperator.id

`attribute` · `python`

```python
id: str = Field(..., description="Stable id: '<subgraph>:<first output tensor name>', or a fallback; operators[].id matches it. For every id_source except node_id, split on the first colon only (tensor names can contain ':'); a node_id id is the opaque AIR node id")
```

Source: `helia_aot/optimization/schema.py:200`

### helia_aot.optimization.schema.PlanOperator.id_source

`attribute` · `python`

```python
id_source: Literal['tensor_name', 'tensor_name+ordinal', 'index', 'node_id'] = Field(..., description='How the id was derived; node_id when the stable id would also match another operator, so the id is the AIR node id')
```

Source: `helia_aot/optimization/schema.py:208`

### helia_aot.optimization.schema.PlanOperator.index

`attribute` · `python`

```python
index: int = Field(..., description='Position in execution order')
```

Source: `helia_aot/optimization/schema.py:215`

### helia_aot.optimization.schema.PlanOperator.node_id

`attribute` · `python`

```python
node_id: str = Field(..., description='AIR node id, which operators[].id also matches')
```

Source: `helia_aot/optimization/schema.py:216`

### helia_aot.optimization.schema.PlanOperator.op_type

`attribute` · `python`

```python
op_type: str
```

Source: `helia_aot/optimization/schema.py:217`

### helia_aot.optimization.schema.PlanOperator.knobs

`attribute` · `python`

```python
knobs: dict[str, KnobChoice] = Field(default_factory=dict, description='Resolved choice per knob, for the knobs that exist for this operator', json_schema_extra=_per_knob(_choice_enums))
```

Source: `helia_aot/optimization/schema.py:218`

### helia_aot.optimization.schema.PlanOperator.fixed

`attribute` · `python`

```python
fixed: dict[str, FixedChoice] = Field(default_factory=dict)
```

Source: `helia_aot/optimization/schema.py:223`

## helia_aot.optimization.schema.OptimizationPlan

`class` · `python`

```python
OptimizationPlan()
```

The normative optimization plan, ``<prefix>_plan.json``.

Source: `helia_aot/optimization/schema.py:271`

### helia_aot.optimization.schema.OptimizationPlan.schema_version

`attribute` · `python`

```python
schema_version: Literal[1] = Field(..., description='Plan schema version')
```

Source: `helia_aot/optimization/schema.py:274`

### helia_aot.optimization.schema.OptimizationPlan.generator

`attribute` · `python`

```python
generator: Generator
```

Source: `helia_aot/optimization/schema.py:275`

### helia_aot.optimization.schema.OptimizationPlan.model

`attribute` · `python`

```python
model: ModelIdentity
```

Source: `helia_aot/optimization/schema.py:276`

### helia_aot.optimization.schema.OptimizationPlan.module_prefix

`attribute` · `python`

```python
module_prefix: str
```

Source: `helia_aot/optimization/schema.py:277`

### helia_aot.optimization.schema.OptimizationPlan.platform

`attribute` · `python`

```python
platform: PlatformIdentity
```

Source: `helia_aot/optimization/schema.py:278`

### helia_aot.optimization.schema.OptimizationPlan.optimization

`attribute` · `python`

```python
optimization: PlanOptimization
```

Source: `helia_aot/optimization/schema.py:279`

### helia_aot.optimization.schema.OptimizationPlan.operators

`attribute` · `python`

```python
operators: list[PlanOperator]
```

Source: `helia_aot/optimization/schema.py:280`

### helia_aot.optimization.schema.OptimizationPlan.tensors

`attribute` · `python`

```python
tensors: list[dict[str, Any]] = Field(default_factory=list, max_length=0, description='Reserved for per-tensor choices such as placement; empty today')
```

Source: `helia_aot/optimization/schema.py:281`

## helia_aot.optimization.schema.ConstantPlacement

`class` · `python`

```python
ConstantPlacement()
```

Constants outside TCM against DTCM left free, within memory.constraints.

Source: `helia_aot/optimization/schema.py:334`

### helia_aot.optimization.schema.ConstantPlacement.constant_bytes_outside_tcm

`attribute` · `python`

```python
constant_bytes_outside_tcm: dict[str, int]
```

Source: `helia_aot/optimization/schema.py:337`

### helia_aot.optimization.schema.ConstantPlacement.constant_bytes_in_tcm

`attribute` · `python`

```python
constant_bytes_in_tcm: int
```

Source: `helia_aot/optimization/schema.py:338`

### helia_aot.optimization.schema.ConstantPlacement.dtcm_budget_bytes

`attribute` · `python`

```python
dtcm_budget_bytes: int
```

Source: `helia_aot/optimization/schema.py:339`

### helia_aot.optimization.schema.ConstantPlacement.dtcm_free_bytes

`attribute` · `python`

```python
dtcm_free_bytes: int
```

Source: `helia_aot/optimization/schema.py:340`

### helia_aot.optimization.schema.ConstantPlacement.id_specific_constant_rules

`attribute` · `python`

```python
id_specific_constant_rules: int
```

Source: `helia_aot/optimization/schema.py:341`

### helia_aot.optimization.schema.ConstantPlacement.cold_source

`attribute` · `python`

```python
cold_source: str | None
```

Source: `helia_aot/optimization/schema.py:342`

## helia_aot.optimization.schema.Hint

`class` · `python`

```python
Hint()
```

One optimization hint: a fact about an alternative that applies.

Source: `helia_aot/optimization/schema.py:345`

### helia_aot.optimization.schema.Hint.setting

`attribute` · `python`

```python
setting: str
```

Source: `helia_aot/optimization/schema.py:348`

### helia_aot.optimization.schema.Hint.message

`attribute` · `python`

```python
message: str
```

Source: `helia_aot/optimization/schema.py:349`

### helia_aot.optimization.schema.Hint.current

`attribute` · `python`

```python
current: str
```

Source: `helia_aot/optimization/schema.py:350`

### helia_aot.optimization.schema.Hint.alternative

`attribute` · `python`

```python
alternative: str
```

Source: `helia_aot/optimization/schema.py:351`

### helia_aot.optimization.schema.Hint.yaml

`attribute` · `python`

```python
yaml: str
```

Source: `helia_aot/optimization/schema.py:352`

### helia_aot.optimization.schema.Hint.operators

`attribute` · `python`

```python
operators: list[str] = Field(default_factory=list)
```

Source: `helia_aot/optimization/schema.py:353`

### helia_aot.optimization.schema.Hint.mac_share

`attribute` · `python`

```python
mac_share: float | None = None
```

Source: `helia_aot/optimization/schema.py:354`

### helia_aot.optimization.schema.Hint.facts

`attribute` · `python`

```python
facts: dict[str, Any] = Field(default_factory=dict)
```

Source: `helia_aot/optimization/schema.py:355`

## helia_aot.optimization.schema.OptimizationReport

`class` · `python`

```python
OptimizationReport()
```

The non-normative optimization report, ``<prefix>_report.json``.

Source: `helia_aot/optimization/schema.py:358`

### helia_aot.optimization.schema.OptimizationReport.schema_version

`attribute` · `python`

```python
schema_version: Literal[1] = Field(..., description='Report schema version')
```

Source: `helia_aot/optimization/schema.py:361`

### helia_aot.optimization.schema.OptimizationReport.plan_file

`attribute` · `python`

```python
plan_file: str = Field(..., description='The plan this report explains')
```

Source: `helia_aot/optimization/schema.py:362`

### helia_aot.optimization.schema.OptimizationReport.total_macs

`attribute` · `python`

```python
total_macs: int = Field(..., description='MACs of convolution, depthwise and fully connected layers')
```

Source: `helia_aot/optimization/schema.py:363`

### helia_aot.optimization.schema.OptimizationReport.operators

`attribute` · `python`

```python
operators: list[ReportOperator]
```

Source: `helia_aot/optimization/schema.py:364`

### helia_aot.optimization.schema.OptimizationReport.measurements

`attribute` · `python`

```python
measurements: dict[str, list[MeasurementRecord]] = Field(..., description='Measurements for this target and core, keyed by setting; every setting has an entry', json_schema_extra=_per_setting)
```

Source: `helia_aot/optimization/schema.py:365`

### helia_aot.optimization.schema.OptimizationReport.constant_placement

`attribute` · `python`

```python
constant_placement: ConstantPlacement | None
```

Source: `helia_aot/optimization/schema.py:370`

### helia_aot.optimization.schema.OptimizationReport.hints

`attribute` · `python`

```python
hints: list[Hint]
```

Source: `helia_aot/optimization/schema.py:371`