Errors

The uniform, traceable error surface for flow failures, plus the cycle-detection error raised during graph construction.

errors

Traceable exception surface for PenguiFlow.

FlowError

FlowError(*, trace_id: str | None, node_name: str | None, code: FlowErrorCode | str, message: str, original_exc: BaseException | None = None, node_id: str | None = None, metadata: Mapping[str, Any] | None = None)

Bases: Exception

Wraps runtime failures with trace metadata for downstream handling.

Attributes:

Name	Type	Description
trace_id		Identifier of the trace during which the failure occurred, if known.
node_name		Name of the node that raised or triggered the failure, if known.
node_id		Identifier of the specific node instance, if known.
code		Stable error code string (see FlowErrorCode).
message		Human-readable description of the failure.
original_exc		The underlying exception that was wrapped, if any.
metadata		Additional structured context attached to the error.
exception_type		Class name of original_exc, or None if not set.

Initialize the error with trace metadata.

Parameters:

Name	Type	Description	Default
trace_id	str | None	Identifier of the trace during which the failure occurred, if known.	required
node_name	str | None	Name of the node that raised or triggered the failure, if known.	required
code	FlowErrorCode | str	Stable error code, either a FlowErrorCode member or a plain string.	required
message	str	Human-readable description of the failure.	required
original_exc	BaseException | None	The underlying exception to wrap, if any.	None
node_id	str | None	Identifier of the specific node instance, if known.	None
metadata	Mapping[str, Any] | None	Additional structured context to attach to the error.	None

trace_id instance-attribute

trace_id = trace_id

node_name instance-attribute

node_name = node_name

node_id instance-attribute

node_id = node_id

code instance-attribute

code = code.value if isinstance(code, FlowErrorCode) else str(code)

message instance-attribute

message = message

original_exc instance-attribute

original_exc = original_exc

metadata instance-attribute

metadata = dict(metadata or {})

exception_type instance-attribute

exception_type = type(original_exc).__name__ if original_exc is not None else None

unwrap

unwrap() -> BaseException | None

Return the wrapped exception, if any.

Returns:

Type	Description
BaseException | None	The original exception passed to the constructor, or None if none was
BaseException | None	provided.

to_payload

to_payload() -> dict[str, Any]

Return a JSON-serialisable representation of the error.

Returns:

Type	Description
dict[str, Any]	A dictionary containing code and message, plus trace_id,
dict[str, Any]	node_name, node_id, exception_type, and metadata when set.

from_exception classmethod

from_exception(*, trace_id: str | None, node_name: str | None, node_id: str | None, exc: BaseException, code: FlowErrorCode, message: str | None = None, metadata: Mapping[str, Any] | None = None) -> FlowError

Build a FlowError from an underlying exception.

Parameters:

Name	Type	Description	Default
trace_id	str | None	Identifier of the trace during which the failure occurred, if known.	required
node_name	str | None	Name of the node that raised or triggered the failure, if known.	required
node_id	str | None	Identifier of the specific node instance, if known.	required
exc	BaseException	The underlying exception to wrap.	required
code	FlowErrorCode	Stable error code describing the failure.	required
message	str | None	Optional human-readable message; defaults to str(exc) or the exception's class name when exc has no message.	None
metadata	Mapping[str, Any] | None	Additional structured context to attach to the error.	None

Returns:

Type	Description
FlowError	A new FlowError wrapping exc.

FlowErrorCode

Bases: str, Enum

Stable error codes surfaced by the runtime.

Attributes:

Name	Type	Description
NODE_TIMEOUT		A node's execution exceeded its configured timeout.
NODE_EXCEPTION		A node raised an unhandled exception during execution.
TRACE_CANCELLED		The trace was cancelled before completion.
DEADLINE_EXCEEDED		The trace's wall-clock deadline was exceeded.
HOP_BUDGET_EXHAUSTED		The trace's hop budget was exhausted.
TOKEN_BUDGET_EXHAUSTED		The trace's token budget was exhausted.

NODE_TIMEOUT class-attribute instance-attribute

NODE_TIMEOUT = 'NODE_TIMEOUT'

NODE_EXCEPTION class-attribute instance-attribute

NODE_EXCEPTION = 'NODE_EXCEPTION'

TRACE_CANCELLED class-attribute instance-attribute

TRACE_CANCELLED = 'TRACE_CANCELLED'

DEADLINE_EXCEEDED class-attribute instance-attribute

DEADLINE_EXCEEDED = 'DEADLINE_EXCEEDED'

HOP_BUDGET_EXHAUSTED class-attribute instance-attribute

HOP_BUDGET_EXHAUSTED = 'HOP_BUDGET_EXHAUSTED'

TOKEN_BUDGET_EXHAUSTED class-attribute instance-attribute

TOKEN_BUDGET_EXHAUSTED = 'TOKEN_BUDGET_EXHAUSTED'

core

Implements Context, Floe, and PenguiFlow runtime with backpressure-aware queues, cycle detection, and graceful shutdown semantics.

CycleError

Bases: RuntimeError

Raised when a cycle is detected in the flow graph.