IR API

lattice_contract contains the backend-neutral dataclasses and semantic operation contracts used by the legacy JSON artifact bridge. It does not import MLX, Torch, native kernels, or sparse runtime objects.

For the conceptual model, read Sparse model IR.

Manifest model

type lattice_contract.manifest.IRInputRef = str | tuple[str, ...]

lattice_contract.manifest.triple(value, *, name)

Normalize an integer or 3-sequence into a spatial integer triple.

Return type:

tuple[int, int, int]

Parameters:

• value (int | Sequence[int])

• name (str)

class lattice_contract.manifest.IRSparseSupport(kind, kernel_size=None, stride=None, padding=None, dilation=None, target=None, mode=None, join=None)

Bases: object

Sparse relation/support attributes for an IR operation.

Parameters:

• kind (str)

• kernel_size (tuple[int, int, int] | None)

• stride (tuple[int, int, int] | None)

• padding (tuple[int, int, int] | None)

• dilation (tuple[int, int, int] | None)

• target (str | None)

• mode (str | None)

• join (str | None)

kind: str

kernel_size: tuple[int, int, int] | None

stride: tuple[int, int, int] | None

padding: tuple[int, int, int] | None

dilation: tuple[int, int, int] | None

target: str | None

mode: str | None

join: str | None

class lattice_contract.manifest.IRTensorSpec(name, type)

Bases: object

Named graph input or output specification.

Parameters:

• name (str)

• type (Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes'])

name: str

type: Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']

class lattice_contract.manifest.IRNode(id, op, inputs, outputs, parameters=<factory>, attributes=<factory>, support=None)

Bases: object

One semantic operation in a lattice model graph.

Parameters:

• id (str)

• op (str)

• inputs (dict[str, IRInputRef])

• outputs (dict[str, str])

• parameters (dict[str, str])

• attributes (dict[str, Any])

• support (IRSparseSupport | None)

id: str

op: str

inputs: dict[str, IRInputRef]

outputs: dict[str, str]

parameters: dict[str, str]

attributes: dict[str, Any]

support: IRSparseSupport | None

class lattice_contract.manifest.IRManifest(schema_version, producer, runtime, inputs, outputs, nodes, dtype_policy='preserve', coordinate_order=('batch', 'x', 'y', 'z'), feature_layout=('row', 'channel'), weight_layout='mlx-lattice')

Bases: object

Validated sparse model manifest.

The manifest is the stable artifact contract shared by future training producers and the MLX artifact loader. It records semantic sparse graph nodes and names the tensor weights stored beside it.

Parameters:

• schema_version (str)

• producer (dict[str, str])

• runtime (dict[str, str])

• inputs (tuple[IRTensorSpec, ...])

• outputs (tuple[IRTensorSpec, ...])

• nodes (tuple[IRNode, ...])

• dtype_policy (Literal['preserve', 'fp32', 'fp16', 'fp16_inference'])

• coordinate_order (tuple[str, ...])

• feature_layout (tuple[str, ...])

• weight_layout (str)

schema_version: str

producer: dict[str, str]

runtime: dict[str, str]

inputs: tuple[IRTensorSpec, ...]

outputs: tuple[IRTensorSpec, ...]

nodes: tuple[IRNode, ...]

dtype_policy: Literal['preserve', 'fp32', 'fp16', 'fp16_inference']

coordinate_order: tuple[str, ...]

feature_layout: tuple[str, ...]

weight_layout: str

lattice_contract.manifest.load_manifest(path)

Load and validate a manifest JSON file.

Return type:

IRManifest

Parameters:

path (str | Path)

lattice_contract.manifest.manifest_from_dict(raw)

Build a validated IRManifest from decoded JSON data.

Return type:

IRManifest

Parameters:

raw (Mapping[str, Any])

lattice_contract.manifest.manifest_to_dict(manifest)

Convert a manifest object to JSON-serializable data.

Return type:

dict[str, Any]

Parameters:

manifest (IRManifest)

lattice_contract.manifest.is_ir_value_type(value)

Return whether value is a supported lattice IR value type.

Return type:

bool

Parameters:

value (str)

lattice_contract.manifest.ir_value_type(value)

Validate and cast a string into IRValueType.

Return type:

Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']

Parameters:

value (str)

Operation registry

The registry exposes explicit semantic operation contracts. It no longer mirrors the full mlx_lattice.ops Python surface, and new cross-framework graph work should target the MLIR lattice dialect rather than adding broad JSON operation coverage.

class lattice_contract.ops.IRParameterKind(*values)

Bases: StrEnum

Storage kind for a persisted operation parameter.

ARRAY = 'array'

OPTIONAL_ARRAY = 'optional_array'

QUANTIZED_WEIGHT = 'quantized_weight'

ARRAY_OR_QUANTIZED_WEIGHT = 'array_or_quantized_weight'

class lattice_contract.ops.IROpSpec(name, inputs, outputs, output_types, input_types=<factory>, value_attribute_types=<factory>, parameters=frozenset({}), optional_parameters=frozenset({}), attributes=frozenset({}), value_attributes=frozenset({}), requires_support=False)

Bases: object

Static graph schema for one lattice IR operation.

Parameters:

• name (str)

• inputs (frozenset[str])

• outputs (frozenset[str])

• output_types (dict[str, Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']])

• input_types (dict[str, Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']])

• value_attribute_types (dict[str, Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']])

• parameters (frozenset[str])

• optional_parameters (frozenset[str])

• attributes (frozenset[str])

• value_attributes (frozenset[str])

• requires_support (bool)

name: str

inputs: frozenset[str]

outputs: frozenset[str]

output_types: dict[str, Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']]

input_types: dict[str, Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']]

value_attribute_types: dict[str, Literal['any', 'sparse_tensor', 'dense_tensor', 'relation', 'coordinate_set', 'alignment', 'quantization', 'point_voxel_map', 'coordinate_ordering', 'sparse_occupancy', 'occupancy_expansion', 'bytes']]

parameters: frozenset[str]

optional_parameters: frozenset[str]

attributes: frozenset[str]

value_attributes: frozenset[str]

requires_support: bool

class lattice_contract.ops.IROpContract(spec, parameter_kinds=<factory>, optional_parameter_kinds=<factory>)

Bases: object

Canonical semantic contract for one lattice IR operation.

Parameters:

• spec (IROpSpec)

• parameter_kinds (Mapping[str, IRParameterKind])

• optional_parameter_kinds (Mapping[str, IRParameterKind])

spec: IROpSpec

parameter_kinds: Mapping[str, IRParameterKind]

optional_parameter_kinds: Mapping[str, IRParameterKind]

property name: str

Return the manifest operation name.

lattice_contract.ops.ir_op_contract(name, *, inputs, outputs, output_types=None, input_types=None, value_attribute_types=None, parameters=None, optional_parameters=None, attributes=None, value_attributes=None, parameter_kinds=None, optional_parameter_kinds=None, requires_support=False)

Create an unregistered lattice IR operation contract.

Return type:

IROpContract

Parameters:

• name (str)

• inputs (set[str] | frozenset[str])

• outputs (set[str] | frozenset[str])

• output_types (Mapping[str, str] | None)

• input_types (Mapping[str, str] | None)

• value_attribute_types (Mapping[str, str] | None)

• parameters (set[str] | frozenset[str] | None)

• optional_parameters (set[str] | frozenset[str] | None)

• attributes (set[str] | frozenset[str] | None)

• value_attributes (set[str] | frozenset[str] | None)

• parameter_kinds (Mapping[str, str | IRParameterKind] | None)

• optional_parameter_kinds (Mapping[str, str | IRParameterKind] | None)

• requires_support (bool)

lattice_contract.ops.register_op_contract(contract)

Register an extension operation contract and return it.

Return type:

IROpContract

Parameters:

contract (IROpContract)

lattice_contract.ops.ir_op_spec(name, *, inputs, outputs, output_types=None, input_types=None, value_attribute_types=None, parameters=None, optional_parameters=None, attributes=None, value_attributes=None, requires_support=False)

Register an extension operation with a compact annotation.

Return type:

Callable[[TypeVar(DeclarationT, bound= Callable)], TypeVar(DeclarationT, bound= Callable)]

Parameters:

• name (str)

• inputs (set[str])

• outputs (set[str])

• output_types (Mapping[str, str] | None)

• input_types (Mapping[str, str] | None)

• value_attribute_types (Mapping[str, str] | None)

• parameters (set[str] | None)

• optional_parameters (set[str] | None)

• attributes (set[str] | None)

• value_attributes (set[str] | None)

• requires_support (bool)

lattice_contract.ops.iter_op_specs()

Iterate registered IR operation specs.

Return type:

Iterator[IROpSpec]

lattice_contract.ops.iter_op_contracts()

Iterate registered canonical IR operation contracts.

Return type:

Iterator[IROpContract]

lattice_contract.ops.op_spec(name)

Return the registered spec for name or raise ValueError.

Return type:

IROpSpec

Parameters:

name (str)

lattice_contract.ops.op_contract(name)

Return the registered operation contract for name.

Return type:

IROpContract

Parameters:

name (str)

lattice_contract.ops.validate_node_against_spec(node)

Validate node ports, parameters, and attributes against its spec.

Return type:

None

Parameters:

node (IRNode)