canvas_engineering.program¶
Typed process semantics for canvas regions and connections.
canvas_engineering.program.ClockSpec
dataclass
¶
When a region updates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
domain
|
str
|
Time domain. "external" = environment time, "boundary" = lifecycle events. |
'external'
|
mode
|
str
|
Firing rule. "periodic" = every N steps, "on_event" = threshold on residual summary, "boundary" = fires on named boundary event. |
'periodic'
|
period
|
int
|
For periodic mode, fire every N steps. |
1
|
event_source
|
Optional[str]
|
For on_event/boundary mode, the source identifier. Format: "region_name.kind_name" for on_event, event name for boundary. |
None
|
event_threshold
|
float
|
For on_event mode, fire when summary exceeds this. |
0.0
|
cooldown
|
int
|
After firing, suppress for this many steps. |
0
|
max_silence
|
Optional[int]
|
Force fire after this many steps of silence. |
None
|
canvas_engineering.program.LearningSpec
dataclass
¶
How a region learns during training.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mode
|
str
|
Learning paradigm. "supervised" = task loss, "ssl_prediction" = self-supervised next-step/masked prediction, "posterior_match" = train student to match teacher posterior, "retrieval" = retrieval accuracy + write utility, "calibration" = uncertainty calibration, "none" = no learning. |
'supervised'
|
losses
|
Tuple[str, ...]
|
Named loss functions to apply. Interpreted by the training loop. |
()
|
compile_mode
|
str
|
What happens at deploy. "runtime" = keep live, "freeze" = no more learning, "distill" = train small student, "constant" = materialize as buffer, "export" = save to disk and remove. |
'runtime'
|
canvas_engineering.program.RegionProgram
dataclass
¶
Process semantics for a canvas region.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
family
|
str
|
What kind of state this region holds. One of: observation, state, memory, residual, action. Custom strings allowed. |
'state'
|
tags
|
Tuple[str, ...]
|
Semantic sub-tags for nuance within a family. E.g., a state region might have tags=("belief", "object") or tags=("goal",). |
()
|
carrier
|
str
|
What dynamics govern this region. "deterministic" = standard forward updates, "diffusive" = noise/denoise, "filter" = predict/ correct, "memory" = persistent lookup, "residual" = error traces. |
'deterministic'
|
clock
|
Optional[ClockSpec]
|
When this region updates. None = always active. |
None
|
learning
|
Optional[LearningSpec]
|
Training recipe. None = use family default. |
None
|
compile_mode
|
str
|
Deploy behavior. "runtime" = keep live, "freeze" = no more learning, "constant" = materialize, "export" = save & remove. |
'runtime'
|
constraints
|
Optional[ConstraintSpec]
|
Structural constraints on dynamics. None = unconstrained. |
None
|
identity
|
Optional['IdentitySpec']
|
Identity/slot persistence spec. None = no identity tracking. |
None
|
canvas_engineering.program.ConnectionProgram
dataclass
¶
Process semantics for a canvas connection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
operator
|
str
|
Semantic intent of this edge. "attend" = generic attention (backward compat default), "observe" = write evidence, "predict" = propagate forward, "correct" = error-driven update, etc. |
'attend'
|
trigger
|
Optional[str]
|
Optional condition for firing. Serializable string expression referencing residual summaries. E.g., "vision.err.prediction > 0.25". |
None
|
write_mode
|
str
|
How output accumulates at destination. "add" = additive (current behavior), "replace" = overwrite, "gate" = learned gate. |
'add'
|
canvas_engineering.program.CanvasProgram
dataclass
¶
Typed process semantics layered on top of CanvasSchema.
The schema declares structure (where things live, who talks to whom). The program declares behavior (what each region is, how it learns, when it updates, what happens at deploy).
Usage
program = CanvasProgram( schema=my_schema, regions={"obs": RegionProgram(family="observation")}, ) program.to_json("my_program.json") loaded = CanvasProgram.from_json("my_program.json")