Skip to content

# 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`

    1

    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:

    1
    2
    3

    - 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

    1

    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

    1

    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

    1

    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`

    1

    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

    1

    keys() -> Iterable[str]

Return top-level keys.

Returns:

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

###### `` update

    1

    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:

    1
    2

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

#### `` Schema `dataclass`

    1

    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:

    1
    2
    3

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

##### Functions

###### `` validate_payload

    1

    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

    1

    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`

    1

    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:

    1
    2
    3
    4

    - 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__

    1

    __repr__() -> str

Concise debug representation.

Avoids printing full data for large states.

###### `` fork

    1

    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:

    1
    2
    3

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

###### `` get

    1

    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

    1

    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

    1

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

Return lineage from root to this State.

Returns:

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