canvas_engineering.types

Compositional type system for latent space. Declare types, compile to canvas schemas.

canvas_engineering.types.Field dataclass

A latent region declaration.

Declares a region of h x w positions on the canvas grid, each carrying the canvas's d_model dimensionality. Default (1, 1) = scalar (1 position).

Parameters:

Name	Type	Description	Default
h	int	Height on the canvas grid. Default 1.	1
w	int	Width on the canvas grid. Default 1.	1
period	int	Canvas frames per real-world update (1 = every frame).	1
is_output	bool	Whether this field participates in diffusion loss.	True
loss_weight	float	Relative loss weight for positions in this field.	1.0
attn	str	Default attention function type for outgoing connections.	'cross_attention'
semantic_type	Optional[str]	Human-readable modality description.	None
temporal_extent	Optional[int]	Number of timesteps this field spans. None = full T.	None
family	Optional[str]	Region family for v2 process semantics. None = infer default ("state"). One of: observation, state, memory, residual, action.	None
tags	Tuple[str, ...]	Semantic sub-tags within a family. E.g., ("belief", "object").	()
carrier	Optional[str]	Dynamics carrier. None = infer default ("deterministic"). One of: deterministic, diffusive, filter, memory, residual.	None

num_positions property

Spatial positions per timestep (h * w).

canvas_engineering.types.LayoutStrategy

Bases: Enum

How to arrange fields on the (H, W) grid.

canvas_engineering.types.ConnectivityPolicy dataclass

Default connectivity rules for compiled schemas.

Every nested type and array element automatically gets a coarse-grained field at its own path. Parent fields connect bidirectionally to the coarse-grained field; the coarse-grained field connects bidirectionally to child fields.

Coarse-grained field size is configured on the types themselves

• Set __coarse__ = Field(h, w) on a class to define its default coarse-grained field size when it appears as a child anywhere.
• Set metadata={"coarse": Field(h, w)} on a dataclass field to override the coarse-grained field for that specific parent->child edge.
• Falls back to Field(1, 1) if neither is set.

Parameters:

Name	Type	Description	Default
intra	str	How fields within a single type connect. "dense" (default), "isolated", "causal_chain", "star"	'dense'
array_element	str	How elements of the same list connect. "isolated" (default), "dense", "matched_fields", "ring"	'isolated'
temporal	str	Temporal constraint policy for all connections. "dense" (default), "causal", "same_frame"	'dense'

canvas_engineering.types.BoundField

A Field bound to a compiled canvas region.

Provides convenient access to place/extract operations via a canvas.

num_positions property

Total positions in this region (T_extent * h * w).

extract(batch, canvas=None)

Read embeddings from this field's canvas region.

indices()

Flat indices for this field's region.

place(batch, embeddings, canvas=None)

Write embeddings into this field's canvas region.

canvas_engineering.types.BoundSchema

A compiled type hierarchy bound to a CanvasSchema.

Provides field access by dotted path and optional canvas binding.

Example

bound = compile_schema(robot, T=8, H=16, W=16, d_model=256) canvas = bound.build_canvas() batch = bound.create_batch(4) bound["camera"].place(batch, camera_embs) actions = bound["action"].extract(batch)

build_canvas(semantic_conditioner=None)

Create and store a SpatiotemporalCanvas for this schema.

Parameters:

Name	Type	Description	Default
semantic_conditioner		Optional SemanticConditioner for semantic embedding conditioning. If provided, replaces learned modality embeddings with frozen semantic embeddings + learned residuals.	None

build_semantic_conditioner(embed_fn, embed_dim=1536, freeze_embeddings=True, learn_residuals=True)

Build a SemanticConditioner from this schema's field paths.

Computes semantic embeddings for all fields using the provided embedding function, then creates a SemanticConditioner.

Parameters:

Name	Type	Description	Default
embed_fn		Callable taking list[str] -> list[list[float]]. Each string is a semantic type description.	required
embed_dim	int	Dimension of the embeddings returned by embed_fn.	1536
freeze_embeddings	bool	If True, freeze the raw embeddings.	True
learn_residuals	bool	If True, add learned residuals.	True

Returns:

Type	Description
	SemanticConditioner ready to use with build_canvas().

Example

conditioner = bound.build_semantic_conditioner(my_embed_fn) canvas = bound.build_canvas(semantic_conditioner=conditioner)

create_batch(batch_size)

Create an empty canvas batch. Builds canvas if needed.

summary()

Human-readable summary of the compiled schema.

canvas_engineering.types.compile_schema(root, T=1, H=None, W=None, d_model=64, connectivity=None, layout_strategy=LayoutStrategy.PACKED, t_current=0)

Compile an object hierarchy into a BoundSchema.

Walks the object tree, finds Field attributes, packs them onto a (T, H, W) grid, generates connectivity based on the type hierarchy, and returns a BoundSchema wrapping the compiled CanvasSchema.

Works with dataclasses, Pydantic models, or plain objects.

When H and/or W are None, they are auto-computed from the declared field dimensions -- like a C compiler sizing a struct from its members.

Every nested type and array element automatically gets a coarse-grained field at its own path. Coarse-grained field size is configured on the types: - __coarse__ = Field(h, w) on the child class - metadata={"coarse": Field(h, w)} on the parent's field - Falls back to Field(1, 1)

Parameters:

Name	Type	Description	Default
root	Any	Object with Field attributes. Lists create array regions.	required
T	int	Temporal extent of the canvas. Default 1.	1
H	Optional[int]	Height of the canvas grid. None = auto-sized.	None
W	Optional[int]	Width of the canvas grid. None = auto-sized.	None
d_model	int	Latent dimensionality per position. Default 64.	64
connectivity	Optional[ConnectivityPolicy]	Connectivity policy. Default: dense intra, isolated arrays, dense temporal.	None
layout_strategy	Union[str, LayoutStrategy]	"packed" (default) or "interleaved".	PACKED
t_current	int	Timestep boundary for output mask.	0

Returns:

Type	Description
BoundSchema	BoundSchema with compiled layout, topology, and bound field access.

Example

from dataclasses import dataclass

@dataclass class Robot: camera: Field = Field(12, 12) joints: Field = Field(1, 8) action: Field = Field(1, 8, loss_weight=2.0)

Auto-sized canvas:

bound = compile_schema(Robot(), T=8, d_model=256)

Explicit canvas:

bound = compile_schema(Robot(), T=8, H=16, W=16, d_model=256)

canvas_engineering.types.compile_program(root, T=1, H=None, W=None, d_model=64, connectivity=None, layout_strategy=LayoutStrategy.PACKED, t_current=0)

Compile an object hierarchy into a BoundSchema + CanvasProgram.

Same as compile_schema() but also generates a CanvasProgram with RegionPrograms derived from Field's family/tags/carrier attributes. Fields without family/carrier get default RegionPrograms.

Parameters:

Name	Type	Description	Default
root	Any	Object with Field attributes.	required
T, H, W, d_model		Canvas dimensions.	required
connectivity	Optional[ConnectivityPolicy]	Connectivity policy.	None
layout_strategy	Union[str, LayoutStrategy]	Packing strategy.	PACKED
t_current	int	Timestep boundary for output mask.	0

Returns:

Type	Description
Tuple[BoundSchema, CanvasProgram]	(BoundSchema, CanvasProgram) tuple.

Example

@dataclass class Robot: camera: Field = Field(12, 12, family="observation") joints: Field = Field(1, 8, family="observation", carrier="deterministic") belief: Field = Field(4, 4, family="state", tags=("belief",)) action: Field = Field(1, 8, family="action", loss_weight=2.0)

bound, program = compile_program(Robot(), T=8, d_model=256)