State

dagpipe.state

Summary

Defines the core State object used by dagpipe.

The State represents a single point in pipeline execution. It contains arbitrary data and metadata and is designed to be immutable. Instead of modifying an existing state, nodes create new child states via fork().

---

Design principles

• Immutability: States must never be modified after creation. All transformations must create a new state via fork().
• Cheap cloning: Forking must be efficient since branching may create many states.
• Lineage tracking: Each state maintains a reference to its parent and execution metadata for debugging and observability.
• Domain agnostic: State contains generic key-value data and does not assume any schema.
• Engine-friendly: State contains execution metadata such as depth and history.

Classes

Payload dataclass

Payload(_data: Mapping[str, Any])

Immutable hierarchical container with dot-path access.

Attributes:

Name	Type	Description
_data	Mapping[str, Any]	Immutable hierarchical data structure.

Notes

Responsibilities:

- Stores execution data used by `State`.
- Supports efficient atomic updates without modifying existing instances.
- `Payload` instances are fully thread-safe due to immutability.

Functions

as_dict

as_dict() -> Mapping[str, Any]

Return underlying mapping.

Returns:

Type	Description
Mapping[str, Any]	Mapping[str, Any]: Read-only view of the underlying data.

get

get(path: str, default: Any = None) -> Any

Retrieve value using dot-path.

Parameters:

Name	Type	Description	Default
path	str	Dot-separated path to the value.	required
default	Any	Default value if path doesn't exist.	None

Returns:

Name	Type	Description
Any	Any	The retrieved value or default.

has

has(path: str) -> bool

Return True if path exists.

Parameters:

Name	Type	Description	Default
path	str	Dot-separated path to check.	required

Returns:

Name	Type	Description
bool	bool	Existence of the path.

iter_paths classmethod

iter_paths(data: Mapping[str, Any], prefix: str = '') -> Iterable[str]

Recursively yield dot-paths for all leaf nodes.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	The mapping to iterate over.	required
prefix	str	Current path prefix.	''

Returns:

Type	Description
Iterable[str]	Iterable[str]: Generator yielding dot-paths.

keys

keys() -> Iterable[str]

Return top-level keys.

Returns:

Type	Description
Iterable[str]	Iterable[str]: Iterator over top-level keys.

update

update(updates: Mapping[str, Any]) -> Payload

Create a new Payload with dot-path updates applied.

Parameters:

Name	Type	Description	Default
updates	Mapping[str, Any]	Dot-path to value mapping.	required

Returns:

Name	Type	Description
Payload	Payload	New immutable payload instance with updates.

Notes

Guarantees:

- Preserves existing data by copying only modified branches.
- Returns a new immutable `Payload`.

Schema dataclass

Schema(tree: Mapping[str, SchemaNode])

Immutable hierarchical schema defining allowed payload structure.

Attributes:

Name	Type	Description
tree	Mapping[str, SchemaNode]	Hierarchical schema definition.

Notes

Responsibilities:

- Validates `State` payloads and updates.
- Reusable across all `State` instances.
- Fully thread-safe due to immutability.

Functions

validate_payload

validate_payload(payload: Payload) -> None

Validate complete payload structure.

Parameters:

Name	Type	Description	Default
payload	Payload	Payload to validate.	required

Raises:

Type	Description
SchemaError	If payload violates schema.

validate_update

validate_update(updates: Mapping[str, Any]) -> None

Validate payload update paths.

Parameters:

Name	Type	Description	Default
updates	Mapping[str, Any]	Dot-path updates to validate.	required

Raises:

Type	Description
SchemaError	If any path is invalid according to the schema.

SchemaError

Bases: Exception

Raised when payload data violates the declared schema.

Indicates invalid structure, invalid path, or invalid type.

State dataclass

State(payload: Payload, confidence: float = 1.0, parent: Optional[State] = None, depth: int = 0, history: Tuple[str, ...] = tuple(), metadata: Dict[str, Any] = dict())

Immutable execution state propagated through dagpipe pipeline.

Attributes:

Name	Type	Description
payload	Payload	Execution data container.
schema	ClassVar[Schema]	Payload validation schema.
confidence	float	Execution confidence score.
parent	Optional[State]	Parent state reference.
depth	int	Execution depth.
history	Tuple[str, ...]	Ordered node execution lineage.
metadata	Dict[str, Any]	Execution metadata.

Notes

Responsibilities:

- Represents a complete execution snapshot at a specific point in
  pipeline traversal.
- Fundamental unit of execution in `dagpipe`.
- Fully thread-safe due to immutability.

Functions

__repr__

__repr__() -> str

Concise debug representation.

Avoids printing full data for large states.

fork

fork(*, payload_update: Optional[Mapping[str, Any]] = None, confidence_delta: float = 0.0, node_id: Optional[str] = None, metadata_update: Optional[Mapping[str, Any]] = None) -> State

Create a new child State derived from this state.

Parameters:

Name	Type	Description	Default
payload_update	Mapping[str, Any]	Dot-path updates applied to the payload.	None
confidence_delta	float	Adjustment applied to current confidence.	0.0
node_id	str	Identifier of the node creating this state.	None
metadata_update	Mapping[str, Any]	Updates merged into state metadata.	None

Returns:

Name	Type	Description
State	State	A new immutable State instance.

Notes

Guarantees:

- This is the only supported mechanism for modifying execution data.
- Validates payload updates, preserves lineage, increments depth,
  and appends to history.

get

get(key: str, default: Any = None) -> Any

Retrieve payload value.

Parameters:

Name	Type	Description	Default
key	str	Dot-path key.	required
default	Any	Fallback value.	None

Returns:

Name	Type	Description
Any	Any	Stored value or default.

has

has(key: str) -> bool

Check whether payload contains key.

Parameters:

Name	Type	Description	Default
key	str	Dot-path key.	required

Returns:

Name	Type	Description
bool	bool	Existence of the key.

lineage

lineage() -> Tuple[State, ...]

Return lineage from root to this State.

Returns:

Type	Description
Tuple[State, ...]	Tuple[State, ...]: Ordered execution lineage (root first).