canvas_engineering.dispatch

Per-connection attention dispatch. Routes each topology connection to its resolved attention function and combines per-edge contributions according to ConnectionProgram.write_mode (add / replace / gate). When a CanvasProgram is attached, the dispatcher also evaluates per-edge trigger expressions, honors per-operator defaults from OPERATOR_DEFAULTS, applies MaskSpec sparsity patterns, runs SlotBindingModule for regions with an IdentitySpec, and lets a CortexRegistry override the attention fn for intra-cortex edges with the cortex's declared local_backend.

canvas_engineering.dispatch.AttentionDispatcher

Bases: Module

Routes attention operations per topology connection.

For each connection in topology.attention_ops(layout): 1. Extract src/dst position indices from layout 2. Gather queries from src positions, keys/values from dst positions 3. Apply temporal fill logic for cross-frequency connections 4. Run the resolved attention function 5. Scale by connection weight 6. Scatter-add results back to output

Multiple connections writing to the same src region accumulate additively and are normalized by the total incoming weight.

Parameters:

Name	Type	Description	Default
topology	CanvasTopology	CanvasTopology declaring connections.	required
layout	CanvasLayout	CanvasLayout declaring region positions.	required
d_model	int	Model dimension.	required
n_heads	int	Number of attention heads.	4
dropout	float	Dropout rate.	0.0
skip_temporal	bool	If True, ignore temporal constraints (t_src/t_dst) and treat all connections as dense-in-time.	False
residual_accumulator		Optional ResidualAccumulator for tracking error summaries on residual-carrier regions. Updated as a side effect during forward(). Access via .summaries property.	None

summaries property

Current residual summaries, or None if no accumulator.

forward(x, active_regions=None, summaries=None)

Run dispatched attention over all topology connections.

Parameters:

Name	Type	Description	Default
x	Tensor	(B, N, d_model) hidden states.	required
active_regions	Optional[Set[str]]	Optional set of region names that should update. If None, all regions fire (backward compatible). If provided, connections where src is not in active_regions are skipped and those positions pass through from x unchanged.	None
summaries	Optional[Dict[str, Dict[str, float]]]	Optional residual summaries used to evaluate per-edge ConnectionProgram.trigger expressions when a program is attached. If None and the dispatcher has a residual accumulator, the accumulator's current summaries are used.	None

Returns:

Type	Description
Tensor	(B, N, d_model) updated hidden states. Positions not in any
Tensor	src region (or in inactive regions) are passed through unchanged.

Write modes (from ConnectionProgram.write_mode): - add (default): contributions are weighted and the resulting accumulator is normalized by total incoming weight. - replace: contribution overwrites the destination position entirely (last-writer-wins among replace edges). - gate: contribution is scaled by a learned per-edge sigmoid gate and summed (no normalization). May coexist with add contributions at the same position; the gated sum is added to the normalized additive value.