canvas_engineering.identity¶
Persistent object identity for canvas regions. Attach an IdentitySpec
to a RegionProgram to have the dispatcher auto-instantiate a
SlotBindingModule for that region: cross-attention from a fixed bank
of identity slots into the region's observations, with optional
birth/death gating for variable-count tracklets.
canvas_engineering.identity.IdentitySpec
dataclass
¶
Declares how a region manages persistent object identity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mode
|
str
|
Identity management mode. "persistent" = slots persist across timesteps (default). "ephemeral" = slots re-created each step. "tracklet" = persistent with birth/death gating. |
'persistent'
|
slot_capacity
|
int
|
Maximum number of identity slots. |
64
|
binding_fn
|
str
|
How observations bind to slots. "cross_attention" (default) = standard cross-attention binding. |
'cross_attention'
|
birth_death
|
bool
|
If True and mode="tracklet", enable learned birth/death gates for dynamic slot management. |
False
|
canvas_engineering.identity.SlotBindingModule
¶
Bases: Module
Binds observations to persistent identity slots via cross-attention.
Maintains a set of learned slot vectors. Each forward call updates slots by cross-attending from slots (queries) to observations (keys/values), producing updated slot representations.
For "tracklet" mode with birth_death=True, also computes a scalar gate per slot indicating whether the slot is alive.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
d_model
|
int
|
Model dimension. |
required |
n_slots
|
int
|
Number of identity slots. |
required |
n_heads
|
int
|
Number of attention heads for cross-attention. |
4
|
birth_death
|
bool
|
Whether to enable birth/death gating. |
False
|
alive_mask(observations)
¶
Get the alive mask for slots after binding.
Only meaningful when birth_death=True.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observations
|
Tensor
|
(B, N_obs, d_model) observation embeddings. |
required |
Returns:
| Type | Description |
|---|---|
Tensor
|
(B, n_slots) boolean tensor. True = slot is alive. |
forward(observations)
¶
Bind observations to slots via cross-attention.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observations
|
Tensor
|
(B, N_obs, d_model) observation embeddings. |
required |
Returns:
| Type | Description |
|---|---|
Tensor
|
(B, n_slots, d_model) updated slot representations. |
Tensor
|
If birth_death is enabled, dead slots are zeroed out. |