spacr.flowview.model

Dependency-free data model for a FlowView run graph.

Classes

Edge	A directed transfer between two nodes.
Node	One immutable snapshot of a pipeline stage or artifact.
NodeKind	The role a node plays in a pipeline graph.
NodeState	Lifecycle state of a pipeline node.
RunGraph	A serialisable snapshot of one FlowView run.

Module Contents

class spacr.flowview.model.Edge

A directed transfer between two nodes.

Parameters:

• src – identifier of the node producing the transfer.

• dst – identifier of the node receiving the transfer.

• label – optional relationship or payload caption, such as "consumes" or "produces".

• volume – optional number of objects, files, or rows transferred; the renderer uses it to scale edge width.

class spacr.flowview.model.Node

One immutable snapshot of a pipeline stage or artifact.

Parameters:

• id – stable identifier used by events and graph edges.

• label – human-readable stage or artifact name shown in FlowView.

• kind – input, process, or output role controlling the node’s meaning and presentation.

• state – current lifecycle state, normalized to NodeState.

• started_at – start time in seconds on the producer’s clock, if known.

• ended_at – completion, failure, or skip time on that clock, if known.

• progress – completed and total work-unit counts, or None before a stage reports progress.

• metrics – named scalar results displayed on the node and retained in exported provenance.

• thumbnail – path of a cached representative image, if provided.

• params – stage configuration or provenance values displayed in the inspector and retained in exports.

• error – formatted failure diagnostic, or None when no failure was recorded.

class spacr.flowview.model.NodeKind

Bases: str, enum.Enum

The role a node plays in a pipeline graph.

Initialize self. See help(type(self)) for accurate signature.

class spacr.flowview.model.NodeState

Bases: str, enum.Enum

Lifecycle state of a pipeline node.

Initialize self. See help(type(self)) for accurate signature.

class spacr.flowview.model.RunGraph

A serialisable snapshot of one FlowView run.

Parameters:

• run_id – stable identifier for the captured run.

• started_at – run start time in seconds on the producer’s clock.

• nodes – node identifiers mapped to their immutable snapshots.

• edges – directed transfers connecting the recorded nodes.

• spacr_version – spaCR version that produced the run.

• settings_digest – hash of the settings used for the run.

classmethod from_dict(payload: Mapping[str, Any]) → RunGraph

Restore a graph from to_dict() output.

Parameters:

payload – mapping with the run_id, started_at, nodes, edges, spacr_version and settings_digest keys to_dict() writes; every key is required and a missing one raises KeyError.

classmethod from_json(payload: str | bytes | bytearray) → RunGraph

Restore a graph from its deterministic JSON record.

Parameters:

payload – JSON text (str, bytes or bytearray) as written by to_json(); it is decoded with json.loads and passed to from_dict().

to_dict() → dict[str, Any]

Return a JSON-compatible canonical representation.

to_json() → str

Serialise the graph deterministically as strict JSON.