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.

Machine-readable model

RuleRefclassThe operators[] rule that set a knob.
KnobSourceclassWho asked for a knob's value; rule is set exactly when kind is operator.
KnobChoiceclassThe resolved value of one knob for one operator.
PlanOperatorclassOne operator's choices.
OptimizationPlanclassThe normative optimization plan, <prefix>plan.json.
ConstantPlacementclassConstants outside TCM against DTCM left free, within memory.constraints.
HintclassOne optimization hint: a fact about an alternative that applies.
OptimizationReportclassThe non-normative optimization report, <prefix>report.json.

RuleRef()

The operators[] rule that set a knob.

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

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

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

KnobSource()

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

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

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

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

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.

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

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

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

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: KnobSource

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

PlanOperator()

One operator’s choices.

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")

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')

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

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

op_type: str

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))

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

OptimizationPlan()

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

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

generator: Generator

model: ModelIdentity

module_prefix: str

platform: PlatformIdentity

optimization: PlanOptimization

operators: list[PlanOperator]

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

ConstantPlacement()

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

constant_bytes_outside_tcm: dict[str, int]

constant_bytes_in_tcm: int

dtcm_budget_bytes: int

dtcm_free_bytes: int

id_specific_constant_rules: int

cold_source: str | None

Hint()

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

setting: str

message: str

current: str

alternative: str

yaml: str

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

mac_share: float | None = None

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

OptimizationReport()

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

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

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

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

operators: list[ReportOperator]

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)

constant_placement: ConstantPlacement | None

hints: list[Hint]