edda-framework 0.14.1__py3-none-any.whl → 0.15.0__py3-none-any.whl

edda/integrations/graph/__init__.py

@@ -0,0 +1,58 @@
+"""
+Durable Graph Integration for Edda.
+
+This module provides integration between pydantic-graph and Edda's durable
+execution framework, making pydantic-graph execution crash-recoverable and
+supporting durable wait operations.
+
+Example:
+    from dataclasses import dataclass
+    from pydantic_graph import BaseNode, Graph, End
+    from edda import workflow, WorkflowContext
+    from edda.integrations.graph import DurableGraph, DurableGraphContext
+
+    @dataclass
+    class MyState:
+        counter: int = 0
+
+    @dataclass
+    class IncrementNode(BaseNode[MyState, None, int]):
+        async def run(self, ctx: DurableGraphContext) -> "CheckNode":
+            ctx.state.counter += 1
+            return CheckNode()
+
+    @dataclass
+    class CheckNode(BaseNode[MyState, None, int]):
+        async def run(self, ctx: DurableGraphContext) -> IncrementNode | End[int]:
+            if ctx.state.counter >= 5:
+                return End(ctx.state.counter)
+            return IncrementNode()
+
+    graph = Graph(nodes=[IncrementNode, CheckNode])
+    durable = DurableGraph(graph)
+
+    @workflow
+    async def counter_workflow(ctx: WorkflowContext) -> int:
+        return await durable.run(
+            ctx,
+            start_node=IncrementNode(),
+            state=MyState(),
+        )
+
+Installation:
+    pip install 'edda-framework[graph]'
+"""
+
+from .context import DurableGraphContext
+from .exceptions import GraphExecutionError
+from .graph import DurableGraph
+from .nodes import ReceivedEvent, Sleep, WaitForEvent
+
+__all__ = [
+    "DurableGraph",
+    "DurableGraphContext",
+    "GraphExecutionError",
+    "ReceivedEvent",
+    "Sleep",
+    "WaitForEvent",
+]

edda/integrations/graph/context.py

@@ -0,0 +1,81 @@
+"""DurableGraphContext - bridges pydantic-graph and Edda contexts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from edda.context import WorkflowContext
+
+    from .nodes import ReceivedEvent
+
+StateT = TypeVar("StateT")
+DepsT = TypeVar("DepsT")
+
+
+@dataclass
+class DurableGraphContext(Generic[StateT, DepsT]):
+    """
+    Context that bridges pydantic-graph and Edda.
+
+    Provides access to:
+    - pydantic-graph's state and deps via properties
+    - last_event: The most recent event received via WaitForEvent
+
+    This context is passed to node's run() method when executing
+    via DurableGraph.
+
+    For durable wait operations (wait_event, sleep), use the WaitForEvent
+    and Sleep marker nodes instead of calling methods directly:
+
+        from edda.integrations.graph import WaitForEvent, Sleep
+
+        @dataclass
+        class MyNode(BaseNode[MyState, None, str]):
+            async def run(self, ctx: DurableGraphContext) -> WaitForEvent[NextNode]:
+                # Return a marker to wait for an event
+                return WaitForEvent(
+                    event_type="payment.completed",
+                    next_node=NextNode(),
+                    timeout_seconds=3600,
+                )
+
+        @dataclass
+        class NextNode(BaseNode[MyState, None, str]):
+            async def run(self, ctx: DurableGraphContext) -> End[str]:
+                # Access the received event
+                event = ctx.last_event
+                return End(event.data.get("status", "unknown"))
+
+    Attributes:
+        state: The graph state object (mutable, shared across nodes)
+        deps: The dependencies object (immutable)
+        last_event: The most recent event received via WaitForEvent (or None)
+        workflow_ctx: The Edda WorkflowContext
+    """
+
+    _state: StateT
+    _deps: DepsT
+    workflow_ctx: WorkflowContext
+    last_event: ReceivedEvent | None = field(default=None)
+
+    @property
+    def state(self) -> StateT:
+        """Get the graph state object."""
+        return self._state
+
+    @property
+    def deps(self) -> DepsT:
+        """Get the dependencies object."""
+        return self._deps
+
+    @property
+    def instance_id(self) -> str:
+        """Get the workflow instance ID."""
+        return self.workflow_ctx.instance_id
+
+    @property
+    def is_replaying(self) -> bool:
+        """Check if the workflow is currently replaying."""
+        return self.workflow_ctx.is_replaying

edda/integrations/graph/exceptions.py

@@ -0,0 +1,9 @@
+"""Exceptions for durable graph integration."""
+
+
+class GraphExecutionError(Exception):
+    """Raised when a graph node execution fails."""
+
+    def __init__(self, message: str, node_name: str | None = None) -> None:
+        self.node_name = node_name
+        super().__init__(message)

edda/integrations/graph/graph.py

@@ -0,0 +1,385 @@
+"""DurableGraph - makes pydantic-graph execution durable via Edda."""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from edda.activity import activity
+from edda.pydantic_utils import to_json_dict
+
+from .context import DurableGraphContext
+from .exceptions import GraphExecutionError
+from .nodes import ReceivedEvent, Sleep, WaitForEvent
+
+if TYPE_CHECKING:
+    from edda.context import WorkflowContext
+
+StateT = TypeVar("StateT")
+DepsT = TypeVar("DepsT")
+RunEndT = TypeVar("RunEndT")
+
+
+def _import_pydantic_graph() -> Any:
+    """Import pydantic_graph with helpful error message."""
+    try:
+        import pydantic_graph
+
+        return pydantic_graph
+    except ImportError as e:
+        msg = (
+            "pydantic-graph is not installed. Install with:\n"
+            "  pip install pydantic-graph\n"
+            "or\n"
+            "  pip install 'edda-framework[graph]'"
+        )
+        raise ImportError(msg) from e
+
+
+def _get_class_path(cls: type) -> str:
+    """Get fully qualified class path for serialization."""
+    return f"{cls.__module__}:{cls.__qualname__}"
+
+
+def _import_class(path: str) -> type:
+    """Import a class from its fully qualified path."""
+    module_path, class_name = path.rsplit(":", 1)
+    module = importlib.import_module(module_path)
+    return getattr(module, class_name)  # type: ignore[no-any-return]
+
+
+def _serialize_node(node: Any) -> dict[str, Any]:
+    """Serialize a node to a dict."""
+    if dataclasses.is_dataclass(node) and not isinstance(node, type):
+        return {
+            "_class_path": _get_class_path(node.__class__),
+            "_data": dataclasses.asdict(node),
+        }
+    return {
+        "_class_path": _get_class_path(node.__class__),
+        "_data": {},
+    }
+
+
+def _deserialize_node(data: dict[str, Any]) -> Any:
+    """Deserialize a node from a dict."""
+    cls = _import_class(data["_class_path"])
+    return cls(**data.get("_data", {}))
+
+
+def _serialize_state(state: Any) -> dict[str, Any]:
+    """Serialize state to a dict."""
+    if state is None:
+        return {"_none": True}
+    if dataclasses.is_dataclass(state) and not isinstance(state, type):
+        return {
+            "_class_path": _get_class_path(state.__class__),
+            "_data": dataclasses.asdict(state),
+        }
+    if hasattr(state, "model_dump"):
+        return {
+            "_class_path": _get_class_path(state.__class__),
+            "_data": state.model_dump(),
+        }
+    return {"_raw": str(state)}
+
+
+def _serialize_deps(deps: Any) -> dict[str, Any] | None:
+    """Serialize deps to a dict."""
+    if deps is None:
+        return None
+    if dataclasses.is_dataclass(deps) and not isinstance(deps, type):
+        return {
+            "_class_path": _get_class_path(deps.__class__),
+            "_data": dataclasses.asdict(deps),
+        }
+    if hasattr(deps, "model_dump"):
+        return {
+            "_class_path": _get_class_path(deps.__class__),
+            "_data": deps.model_dump(),
+        }
+    # For simple types (int, str, etc.), return as-is wrapped
+    return {"_value": deps}
+
+
+def _deserialize_deps(data: dict[str, Any] | None) -> Any:
+    """Deserialize deps from a dict."""
+    if data is None:
+        return None
+    if "_value" in data:
+        return data["_value"]
+    cls = _import_class(data["_class_path"])
+    if dataclasses.is_dataclass(cls):
+        return cls(**data["_data"])
+    if hasattr(cls, "model_validate"):
+        return cls.model_validate(data["_data"])
+    return cls(**data["_data"])
+
+
+def _deserialize_state(data: dict[str, Any]) -> Any:
+    """Deserialize state from a dict."""
+    if data.get("_none"):
+        return None
+    if "_raw" in data:
+        raise ValueError(f"Cannot deserialize state from raw: {data['_raw']}")
+    cls = _import_class(data["_class_path"])
+    if dataclasses.is_dataclass(cls):
+        return cls(**data["_data"])
+    if hasattr(cls, "model_validate"):
+        return cls.model_validate(data["_data"])
+    return cls(**data["_data"])
+
+
+def _restore_state(source: Any, target: Any) -> None:
+    """Copy state from source to target object."""
+    if dataclasses.is_dataclass(source) and not isinstance(source, type):
+        for field in dataclasses.fields(source):
+            setattr(target, field.name, getattr(source, field.name))
+    elif hasattr(source, "__dict__"):
+        for key, value in source.__dict__.items():
+            if not key.startswith("_"):
+                setattr(target, key, value)
+
+
+@activity
+async def _run_graph_node(
+    ctx: WorkflowContext,
+    node_data: dict[str, Any],
+    state_data: dict[str, Any],
+    deps_data: dict[str, Any] | None,
+    last_event_data: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Execute a single graph node as a durable activity.
+
+    This activity is the core of DurableGraph - it runs one node and returns
+    the serialized result (next node, End, WaitForEvent, or Sleep) along
+    with the updated state.
+    """
+    pg = _import_pydantic_graph()
+
+    # Deserialize node, state, and deps
+    node = _deserialize_node(node_data)
+    state = _deserialize_state(state_data)
+    deps = _deserialize_deps(deps_data)
+
+    # Reconstruct last_event if provided
+    last_event: ReceivedEvent | None = None
+    if last_event_data:
+        last_event = ReceivedEvent(
+            event_type=last_event_data.get("event_type", ""),
+            data=last_event_data.get("data", {}),
+            metadata=last_event_data.get("metadata", {}),
+        )
+
+    # Create durable context
+    durable_ctx = DurableGraphContext(
+        _state=state,
+        _deps=deps,
+        workflow_ctx=ctx,
+        last_event=last_event,
+    )
+
+    try:
+        # Execute the node
+        result = await node.run(durable_ctx)
+
+        # Serialize result based on type
+        if isinstance(result, pg.End):
+            return {
+                "_type": "End",
+                "_data": to_json_dict(result.data),
+                "_state": _serialize_state(state),
+            }
+        elif isinstance(result, WaitForEvent):
+            return {
+                "_type": "WaitForEvent",
+                "_event_type": result.event_type,
+                "_timeout_seconds": result.timeout_seconds,
+                "_next_node": _serialize_node(result.next_node),
+                "_state": _serialize_state(state),
+            }
+        elif isinstance(result, Sleep):
+            return {
+                "_type": "Sleep",
+                "_seconds": result.seconds,
+                "_next_node": _serialize_node(result.next_node),
+                "_state": _serialize_state(state),
+            }
+        else:
+            # Regular node transition
+            return {
+                "_type": "Node",
+                "_node": _serialize_node(result),
+                "_state": _serialize_state(state),
+            }
+
+    except Exception as e:
+        raise GraphExecutionError(
+            f"Node {node.__class__.__name__} failed: {e}",
+            node.__class__.__name__,
+        ) from e
+
+
+class DurableGraph(Generic[StateT, DepsT, RunEndT]):
+    """
+    Wrapper that makes pydantic-graph execution durable.
+
+    DurableGraph wraps a pydantic-graph Graph and executes it with Edda's
+    durability guarantees:
+
+    - Each node execution is recorded as an Edda Activity
+    - On replay, completed nodes return cached results (no re-execution)
+    - Crash recovery: workflows resume from the last completed node
+    - WaitForEvent/Sleep markers enable durable wait operations
+
+    Example:
+        from dataclasses import dataclass
+        from pydantic_graph import BaseNode, Graph, End
+        from edda import workflow, WorkflowContext
+        from edda.integrations.graph import (
+            DurableGraph,
+            DurableGraphContext,
+            WaitForEvent,
+        )
+
+        @dataclass
+        class OrderState:
+            order_id: str | None = None
+
+        @dataclass
+        class ProcessOrder(BaseNode[OrderState, None, str]):
+            order_id: str
+
+            async def run(self, ctx: DurableGraphContext) -> WaitForEvent[WaitPayment]:
+                ctx.state.order_id = self.order_id
+                return WaitForEvent(
+                    event_type="payment.completed",
+                    next_node=WaitPayment(),
+                )
+
+        @dataclass
+        class WaitPayment(BaseNode[OrderState, None, str]):
+            async def run(self, ctx: DurableGraphContext) -> End[str]:
+                # Access the received event
+                event = ctx.last_event
+                if event and event.data.get("status") == "success":
+                    return End("completed")
+                return End("failed")
+
+        graph = Graph(nodes=[ProcessOrder, WaitPayment])
+        durable = DurableGraph(graph)
+
+        @workflow
+        async def order_workflow(ctx: WorkflowContext, order_id: str) -> str:
+            return await durable.run(
+                ctx,
+                start_node=ProcessOrder(order_id=order_id),
+                state=OrderState(),
+            )
+    """
+
+    def __init__(self, graph: Any) -> None:
+        """
+        Initialize DurableGraph wrapper.
+
+        Args:
+            graph: A pydantic-graph Graph instance
+
+        Raises:
+            TypeError: If graph is not a pydantic-graph Graph instance
+        """
+        pg = _import_pydantic_graph()
+        if not isinstance(graph, pg.Graph):
+            raise TypeError(f"Expected pydantic_graph.Graph, got {type(graph).__name__}")
+        self._graph = graph
+
+    @property
+    def graph(self) -> Any:
+        """Get the underlying pydantic-graph Graph instance."""
+        return self._graph
+
+    async def run(
+        self,
+        ctx: WorkflowContext,
+        start_node: Any,
+        *,
+        state: StateT,
+        deps: DepsT = None,  # type: ignore[assignment]
+    ) -> RunEndT:
+        """
+        Execute the graph durably with Edda crash recovery.
+
+        Args:
+            ctx: Edda WorkflowContext
+            start_node: The initial node to start execution from
+            state: Initial graph state (will be mutated during execution)
+            deps: Optional dependencies accessible via ctx.deps
+
+        Returns:
+            The final result (End.data value)
+
+        Raises:
+            GraphExecutionError: If graph execution fails
+        """
+        from edda.channels import sleep as edda_sleep
+        from edda.channels import wait_event as edda_wait_event
+
+        current_node = start_node
+        last_event_data: dict[str, Any] | None = None
+
+        # Execute nodes until End is reached
+        while True:
+            # Serialize inputs
+            node_data = _serialize_node(current_node)
+            state_data = _serialize_state(state)
+            deps_data = _serialize_deps(deps)
+
+            # Run node as activity (handles replay/caching automatically)
+            # The @activity decorator transforms the function signature
+            result = await _run_graph_node(  # type: ignore[misc,call-arg]
+                ctx,  # type: ignore[arg-type]
+                node_data,
+                state_data,
+                deps_data,
+                last_event_data,
+            )
+
+            # Restore state from result
+            restored_state = _deserialize_state(result["_state"])
+            _restore_state(restored_state, state)
+
+            # Handle result based on type
+            if result["_type"] == "End":
+                return result["_data"]  # type: ignore[no-any-return]
+
+            elif result["_type"] == "WaitForEvent":
+                # Wait for event at workflow level (outside activity)
+                event = await edda_wait_event(
+                    ctx,
+                    result["_event_type"],
+                    timeout_seconds=result.get("_timeout_seconds"),
+                )
+                # Store event data for next node
+                # Note: edda.channels.ReceivedEvent uses 'type' not 'event_type'
+                last_event_data = {
+                    "event_type": getattr(event, "type", result["_event_type"]),
+                    "data": event.data if isinstance(event.data, dict) else {},
+                    "metadata": getattr(event, "extensions", {}),
+                }
+                # Move to next node
+                current_node = _deserialize_node(result["_next_node"])
+
+            elif result["_type"] == "Sleep":
+                # Sleep at workflow level (outside activity)
+                await edda_sleep(ctx, result["_seconds"])
+                # Clear last_event since this wasn't an event wait
+                last_event_data = None
+                # Move to next node
+                current_node = _deserialize_node(result["_next_node"])
+
+            else:
+                # Regular node transition
+                last_event_data = None  # Clear last_event for regular transitions
+                current_node = _deserialize_node(result["_node"])

edda/integrations/graph/nodes.py

@@ -0,0 +1,144 @@
+"""Marker nodes for durable graph operations.
+
+These are special marker classes that tell DurableGraph to perform
+workflow-level operations (wait_event, sleep) outside of activities.
+
+This design keeps activities pure (atomic, retryable units of work)
+while allowing graphs to wait for external events or sleep.
+
+These classes inherit from pydantic-graph's BaseNode so they can be:
+1. Included in return type annotations without type: ignore
+2. Registered in Graph for proper type validation
+3. Detected by graph visualization tools
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+NextT = TypeVar("NextT")
+
+# Try to import BaseNode for inheritance
+# If pydantic-graph is not installed, use a fallback
+try:
+    from pydantic_graph import BaseNode
+
+    _HAS_PYDANTIC_GRAPH = True
+except ImportError:
+    _HAS_PYDANTIC_GRAPH = False
+
+    # Fallback base class when pydantic-graph is not installed
+    class BaseNode:  # type: ignore[no-redef]
+        pass
+
+
+if TYPE_CHECKING:
+    from pydantic_graph import BaseNode as _BaseNode
+
+    # For type checking, we need the actual BaseNode
+    _MarkerBase = _BaseNode[Any, Any, Any]
+else:
+    _MarkerBase = BaseNode
+
+
+@dataclass
+class WaitForEvent(_MarkerBase, Generic[NextT]):  # type: ignore[misc,valid-type]
+    """
+    Marker node that tells DurableGraph to wait for an external event.
+
+    When a node returns this marker, DurableGraph will:
+    1. Complete the current node's activity
+    2. Call wait_event() at the workflow level (outside activities)
+    3. Store the received event data in ctx.last_event
+    4. Continue execution with next_node
+
+    IMPORTANT: Register this class in your Graph for type checking:
+        graph = Graph(nodes=[MyNode1, MyNode2, WaitForEvent])
+
+    Example:
+        @dataclass
+        class WaitForPaymentNode(BaseNode[OrderState, None, str]):
+            async def run(
+                self, ctx: DurableGraphContext
+            ) -> WaitForEvent[ProcessPaymentNode] | End[str]:
+                ctx.state.waiting_for = "payment"
+                return WaitForEvent(
+                    event_type=f"payment.{ctx.state.order_id}",
+                    next_node=ProcessPaymentNode(),
+                    timeout_seconds=3600,
+                )
+
+        @dataclass
+        class ProcessPaymentNode(BaseNode[OrderState, None, str]):
+            async def run(self, ctx: DurableGraphContext) -> End[str]:
+                event = ctx.last_event
+                if event.data.get("status") == "success":
+                    return End("payment_received")
+                return End("payment_failed")
+
+        # Register WaitForEvent in the Graph
+        graph = Graph(nodes=[WaitForPaymentNode, ProcessPaymentNode, WaitForEvent])
+    """
+
+    event_type: str
+    next_node: NextT
+    timeout_seconds: int | None = None
+
+    async def run(self, _ctx: Any) -> Any:
+        """Never called - DurableGraph intercepts this marker."""
+        raise RuntimeError(
+            "WaitForEvent marker should not be executed directly. "
+            "Use DurableGraph.run() instead of Graph.run()."
+        )
+
+
+@dataclass
+class Sleep(_MarkerBase, Generic[NextT]):  # type: ignore[misc,valid-type]
+    """
+    Marker node that tells DurableGraph to sleep before continuing.
+
+    When a node returns this marker, DurableGraph will:
+    1. Complete the current node's activity
+    2. Call sleep() at the workflow level (outside activities)
+    3. Continue execution with next_node
+
+    IMPORTANT: Register this class in your Graph for type checking:
+        graph = Graph(nodes=[MyNode1, MyNode2, Sleep])
+
+    Example:
+        @dataclass
+        class RateLimitNode(BaseNode[ApiState, None, str]):
+            async def run(
+                self, ctx: DurableGraphContext
+            ) -> Sleep[RetryApiNode] | End[str]:
+                if rate_limited:
+                    return Sleep(seconds=60, next_node=RetryApiNode())
+                return End("success")
+
+        # Register Sleep in the Graph
+        graph = Graph(nodes=[RateLimitNode, RetryApiNode, Sleep])
+    """
+
+    seconds: int
+    next_node: NextT
+
+    async def run(self, _ctx: Any) -> Any:
+        """Never called - DurableGraph intercepts this marker."""
+        raise RuntimeError(
+            "Sleep marker should not be executed directly. "
+            "Use DurableGraph.run() instead of Graph.run()."
+        )
+
+
+@dataclass
+class ReceivedEvent:
+    """
+    Event data received from wait_event.
+
+    This is stored in DurableGraphContext.last_event after WaitForEvent completes.
+    """
+
+    event_type: str
+    data: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)

edda/integrations/llamaindex/__init__.py

@@ -0,0 +1,51 @@
+"""
+LlamaIndex Workflow Integration for Edda.
+
+This module provides integration between LlamaIndex Workflow and Edda's durable
+execution framework, making workflow execution crash-recoverable and supporting
+durable wait operations.
+
+Example:
+    from llama_index.core.workflow import Workflow, step, Event, StartEvent, StopEvent
+    from edda import workflow, WorkflowContext
+    from edda.integrations.llamaindex import DurableWorkflowRunner, DurableSleepEvent
+
+    # Define events
+    class ProcessedEvent(Event):
+        data: str
+
+    # Define workflow
+    class MyWorkflow(Workflow):
+        @step
+        async def process(self, ctx: Context, ev: StartEvent) -> ProcessedEvent:
+            return ProcessedEvent(data=f"processed: {ev.input}")
+
+        @step
+        async def finalize(self, ctx: Context, ev: ProcessedEvent) -> StopEvent:
+            return StopEvent(result={"status": "done", "data": ev.data})
+
+    # Create durable runner
+    runner = DurableWorkflowRunner(MyWorkflow)
+
+    # Use in Edda workflow
+    @workflow
+    async def my_workflow(ctx: WorkflowContext, input_data: str) -> dict:
+        result = await runner.run(ctx, input=input_data)
+        return result
+
+Installation:
+    pip install 'edda-framework[llamaindex]'
+"""
+
+from .events import DurableSleepEvent, DurableWaitEvent, ResumeEvent
+from .exceptions import WorkflowExecutionError, WorkflowReplayError
+from .workflow import DurableWorkflowRunner
+
+__all__ = [
+    "DurableWorkflowRunner",
+    "DurableSleepEvent",
+    "DurableWaitEvent",
+    "ResumeEvent",
+    "WorkflowExecutionError",
+    "WorkflowReplayError",
+]

edda/integrations/llamaindex/events.py

@@ -0,0 +1,160 @@
+"""Durable events for LlamaIndex Workflow integration.
+
+These events signal to the DurableWorkflow that a durable operation
+(sleep or wait for external event) should be performed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+# Lazy import to avoid requiring llama-index at import time
+if TYPE_CHECKING:
+    pass
+
+
+def _import_event_class() -> type[Any]:
+    """Import Event class with helpful error message."""
+    try:
+        from llama_index.core.workflow import Event  # type: ignore[import-not-found]
+
+        return Event  # type: ignore[no-any-return]
+    except ImportError as e:
+        msg = (
+            "llama-index-core is not installed. Install with:\n"
+            "  pip install llama-index-core\n"
+            "or\n"
+            "  pip install 'edda-framework[llamaindex]'"
+        )
+        raise ImportError(msg) from e
+
+
+class DurableSleepEvent:
+    """
+    Event that signals a durable sleep operation.
+
+    When a step returns this event, the DurableWorkflow will:
+    1. Record the step completion
+    2. Call Edda's sleep() function (durable timer)
+    3. Resume with the specified resume_data after the sleep completes
+
+    Example:
+        @step
+        async def rate_limited_step(self, ctx: Context, ev: SomeEvent) -> DurableSleepEvent:
+            # Hit rate limit, need to wait
+            return DurableSleepEvent(
+                seconds=60,
+                resume_data={"retry_count": ev.retry_count + 1},
+            )
+    """
+
+    def __init__(
+        self,
+        seconds: float,
+        resume_data: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Initialize a durable sleep event.
+
+        Args:
+            seconds: Number of seconds to sleep
+            resume_data: Data to include when resuming after sleep
+        """
+        self.seconds = seconds
+        self.resume_data = resume_data or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "_type": "DurableSleepEvent",
+            "seconds": self.seconds,
+            "resume_data": self.resume_data,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DurableSleepEvent:
+        """Deserialize from dictionary."""
+        return cls(
+            seconds=data["seconds"],
+            resume_data=data.get("resume_data", {}),
+        )
+
+
+class DurableWaitEvent:
+    """
+    Event that signals waiting for an external event.
+
+    When a step returns this event, the DurableWorkflow will:
+    1. Record the step completion
+    2. Call Edda's wait_event() function (durable event subscription)
+    3. Resume with the received event data after the event arrives
+
+    Example:
+        @step
+        async def wait_for_approval(self, ctx: Context, ev: OrderEvent) -> DurableWaitEvent:
+            return DurableWaitEvent(
+                event_type=f"approval.{ev.order_id}",
+                timeout_seconds=3600,  # 1 hour timeout
+            )
+    """
+
+    def __init__(
+        self,
+        event_type: str,
+        timeout_seconds: float | None = None,
+    ) -> None:
+        """
+        Initialize a durable wait event.
+
+        Args:
+            event_type: The event type to wait for (e.g., "payment.completed")
+            timeout_seconds: Optional timeout in seconds
+        """
+        self.event_type = event_type
+        self.timeout_seconds = timeout_seconds
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "_type": "DurableWaitEvent",
+            "event_type": self.event_type,
+            "timeout_seconds": self.timeout_seconds,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DurableWaitEvent:
+        """Deserialize from dictionary."""
+        return cls(
+            event_type=data["event_type"],
+            timeout_seconds=data.get("timeout_seconds"),
+        )
+
+
+class ResumeEvent:
+    """
+    Event used to resume workflow after a durable operation.
+
+    This is an internal event type used by DurableWorkflow to resume
+    execution after a DurableSleepEvent or DurableWaitEvent completes.
+    """
+
+    def __init__(self, data: dict[str, Any] | None = None) -> None:
+        """
+        Initialize a resume event.
+
+        Args:
+            data: Data from the completed operation (sleep resume_data or received event)
+        """
+        self.data = data or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "_type": "ResumeEvent",
+            "data": self.data,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ResumeEvent:
+        """Deserialize from dictionary."""
+        return cls(data=data.get("data", {}))

edda/integrations/llamaindex/exceptions.py

@@ -0,0 +1,15 @@
+"""Exceptions for LlamaIndex Workflow integration."""
+
+
+class WorkflowExecutionError(Exception):
+    """Error during workflow execution."""
+
+    def __init__(self, message: str, step_name: str | None = None) -> None:
+        self.step_name = step_name
+        super().__init__(message)
+
+
+class WorkflowReplayError(Exception):
+    """Error during workflow replay."""
+
+    pass

edda/integrations/llamaindex/workflow.py

@@ -0,0 +1,306 @@
+"""DurableWorkflow - makes LlamaIndex Workflow execution durable via Edda.
+
+This module provides integration between LlamaIndex Workflow and Edda's durable
+execution framework, making workflow execution crash-recoverable and supporting
+durable wait operations.
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from edda.activity import activity
+from edda.pydantic_utils import to_json_dict
+
+from .events import DurableSleepEvent, DurableWaitEvent, ResumeEvent
+from .exceptions import WorkflowExecutionError
+
+if TYPE_CHECKING:
+    from edda.context import WorkflowContext
+
+T = TypeVar("T")
+
+
+def _import_llamaindex_workflow() -> Any:
+    """Import llama_index.core.workflow with helpful error message."""
+    try:
+        from llama_index.core import workflow  # type: ignore[import-not-found]
+
+        return workflow
+    except ImportError as e:
+        msg = (
+            "llama-index-core is not installed. Install with:\n"
+            "  pip install llama-index-core\n"
+            "or\n"
+            "  pip install 'edda-framework[llamaindex]'"
+        )
+        raise ImportError(msg) from e
+
+
+def _serialize_event(event: Any) -> dict[str, Any]:
+    """Serialize a LlamaIndex Event to a dictionary."""
+    if isinstance(event, DurableSleepEvent):
+        return event.to_dict()
+    if isinstance(event, DurableWaitEvent):
+        return event.to_dict()
+    if isinstance(event, ResumeEvent):
+        return event.to_dict()
+
+    # For LlamaIndex events, use model_dump if available (Pydantic)
+    if hasattr(event, "model_dump"):
+        data = event.model_dump()
+    elif hasattr(event, "__dict__"):
+        data = {k: v for k, v in event.__dict__.items() if not k.startswith("_")}
+    else:
+        data = {}
+
+    return {
+        "_type": f"{event.__class__.__module__}:{event.__class__.__qualname__}",
+        "_data": to_json_dict(data),
+    }
+
+
+def _deserialize_event(data: dict[str, Any]) -> Any:
+    """Deserialize a dictionary to a LlamaIndex Event."""
+    event_type = data.get("_type", "")
+
+    # Handle our special events
+    if event_type == "DurableSleepEvent":
+        return DurableSleepEvent.from_dict(data)
+    if event_type == "DurableWaitEvent":
+        return DurableWaitEvent.from_dict(data)
+    if event_type == "ResumeEvent":
+        return ResumeEvent.from_dict(data)
+
+    # Handle LlamaIndex events
+    if ":" in event_type:
+        module_path, class_name = event_type.rsplit(":", 1)
+        module = importlib.import_module(module_path)
+        event_class = getattr(module, class_name)
+        event_data = data.get("_data", {})
+
+        # Use model_validate for Pydantic models
+        if hasattr(event_class, "model_validate"):
+            return event_class.model_validate(event_data)
+        return event_class(**event_data)
+
+    raise ValueError(f"Unknown event type: {event_type}")
+
+
+@dataclass
+class StepResult:
+    """Result of a step execution."""
+
+    event: Any
+    step_name: str
+
+
+@activity
+async def _run_step(
+    ctx: WorkflowContext,  # noqa: ARG001 - Used by @activity decorator
+    workflow_class_path: str,
+    step_name: str,
+    event_data: dict[str, Any],
+    context_data: dict[str, Any],
+) -> dict[str, Any]:
+    """
+    Execute a single workflow step as a durable activity.
+
+    This activity is the core of DurableWorkflow - it runs one step and returns
+    the serialized result event.
+    """
+    # Import the workflow class
+    module_path, class_name = workflow_class_path.rsplit(":", 1)
+    module = importlib.import_module(module_path)
+    workflow_class = getattr(module, class_name)
+
+    # Create workflow instance
+    workflow_instance = workflow_class()
+
+    # Deserialize the input event
+    input_event = _deserialize_event(event_data)
+
+    # Get the step method
+    step_method = getattr(workflow_instance, step_name, None)
+    if step_method is None:
+        raise WorkflowExecutionError(f"Step '{step_name}' not found", step_name)
+
+    # Create a minimal context for the step
+    # Note: LlamaIndex Context is created per-run, we create a simple mock
+
+    # Execute the step
+    try:
+        # The step method signature is: async def step(self, ctx, event) -> Event
+        # We need to provide a context - use a simple object with store
+        @dataclass
+        class SimpleContext:
+            store: dict[str, Any]
+
+        simple_ctx = SimpleContext(store=context_data.get("store", {}))
+        result_event = await step_method(simple_ctx, input_event)
+    except Exception as e:
+        raise WorkflowExecutionError(f"Step '{step_name}' failed: {e}", step_name) from e
+
+    # Serialize the result
+    return {
+        "event": _serialize_event(result_event),
+        "context_store": simple_ctx.store,
+    }
+
+
+class DurableWorkflowRunner:
+    """
+    Runner that executes a LlamaIndex Workflow with Edda durability.
+
+    This class wraps a LlamaIndex Workflow and executes it step-by-step,
+    recording each step as an Edda Activity for crash recovery.
+
+    Example:
+        from llama_index.core.workflow import Workflow, step, StartEvent, StopEvent
+
+        class MyWorkflow(Workflow):
+            @step
+            async def process(self, ctx: Context, ev: StartEvent) -> StopEvent:
+                return StopEvent(result="done")
+
+        runner = DurableWorkflowRunner(MyWorkflow)
+
+        @workflow
+        async def my_edda_workflow(ctx: WorkflowContext) -> str:
+            result = await runner.run(ctx, input_data="hello")
+            return result
+    """
+
+    def __init__(self, workflow_class: type) -> None:
+        """
+        Initialize DurableWorkflowRunner.
+
+        Args:
+            workflow_class: A LlamaIndex Workflow class (not instance)
+        """
+        self._workflow_class = workflow_class
+        self._class_path = f"{workflow_class.__module__}:{workflow_class.__qualname__}"
+
+        # Validate it's a Workflow subclass
+        llamaindex_workflow = _import_llamaindex_workflow()
+        if not issubclass(workflow_class, llamaindex_workflow.Workflow):
+            raise TypeError(f"Expected a Workflow subclass, got {type(workflow_class).__name__}")
+
+    async def run(
+        self,
+        ctx: WorkflowContext,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Execute the workflow durably with Edda crash recovery.
+
+        Args:
+            ctx: Edda WorkflowContext
+            **kwargs: Arguments passed to StartEvent
+
+        Returns:
+            The result from StopEvent
+        """
+        from edda.channels import sleep as edda_sleep
+        from edda.channels import wait_event as edda_wait_event
+
+        llamaindex_workflow = _import_llamaindex_workflow()
+
+        # Create a workflow instance to analyze its steps
+        workflow_instance = self._workflow_class()
+
+        # Build step registry from the workflow
+        step_registry = self._build_step_registry(workflow_instance)
+
+        # Start with StartEvent
+        start_event_class = llamaindex_workflow.StartEvent
+        current_event = start_event_class(**kwargs)
+        context_store: dict[str, Any] = {}
+
+        # Main execution loop
+        while True:
+            # Find the step that handles this event type
+            event_type = type(current_event)
+            step_name = self._find_step_for_event(step_registry, event_type)
+
+            if step_name is None:
+                # No step found - check if it's a stop event
+                if isinstance(current_event, llamaindex_workflow.StopEvent):
+                    return current_event.result
+                raise WorkflowExecutionError(f"No step found for event type: {event_type.__name__}")
+
+            # Execute the step as an activity
+            result = await _run_step(  # type: ignore[misc,call-arg]
+                ctx,  # type: ignore[arg-type]
+                self._class_path,
+                step_name,
+                _serialize_event(current_event),
+                {"store": context_store},
+            )
+
+            # Update context store
+            context_store = result.get("context_store", {})
+
+            # Deserialize the result event
+            result_event = _deserialize_event(result["event"])
+
+            # Handle special durable events
+            if isinstance(result_event, DurableSleepEvent):
+                # Durable sleep
+                await edda_sleep(ctx, int(result_event.seconds))
+                # Resume with ResumeEvent containing the sleep's resume_data
+                current_event = ResumeEvent(data=result_event.resume_data)
+
+            elif isinstance(result_event, DurableWaitEvent):
+                # Durable wait for external event
+                received = await edda_wait_event(
+                    ctx,
+                    result_event.event_type,
+                    timeout_seconds=(
+                        int(result_event.timeout_seconds) if result_event.timeout_seconds else None
+                    ),
+                )
+                # Resume with ResumeEvent containing the received data
+                current_event = ResumeEvent(data=received.data if hasattr(received, "data") else {})
+
+            elif isinstance(result_event, llamaindex_workflow.StopEvent):
+                # Workflow completed
+                return result_event.result
+
+            else:
+                # Normal event transition
+                current_event = result_event
+
+    def _build_step_registry(self, workflow_instance: Any) -> dict[str, list[type]]:
+        """Build a registry mapping step names to their input event types."""
+        registry: dict[str, list[type]] = {}
+
+        # Look for methods decorated with @step in the class
+        workflow_class = type(workflow_instance)
+        for name in dir(workflow_class):
+            if name.startswith("_"):
+                continue
+
+            # Get the raw function from the class (not bound method)
+            method = getattr(workflow_class, name, None)
+            if method is None or not callable(method):
+                continue
+
+            # Check if it's a step (has _step_config attribute from @step decorator)
+            if hasattr(method, "_step_config"):
+                step_config = method._step_config
+                # Get accepted event types directly from step config
+                if hasattr(step_config, "accepted_events"):
+                    registry[name] = list(step_config.accepted_events)
+
+        return registry
+
+    def _find_step_for_event(self, registry: dict[str, list[type]], event_type: type) -> str | None:
+        """Find the step that handles the given event type."""
+        for step_name, accepted_types in registry.items():
+            for accepted_type in accepted_types:
+                if issubclass(event_type, accepted_type):
+                    return step_name
+        return None

{edda_framework-0.14.1.dist-info → edda_framework-0.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.14.1
+Version: 0.15.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -42,6 +42,10 @@ Requires-Dist: starlette>=0.40.0; extra == 'dev'
 Requires-Dist: testcontainers[mysql]>=4.0.0; extra == 'dev'
 Requires-Dist: testcontainers[postgres]>=4.0.0; extra == 'dev'
 Requires-Dist: tsuno>=0.1.3; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: pydantic-graph>=0.1.0; extra == 'graph'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.12.0; extra == 'llamaindex'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.22.0; extra == 'mcp'
 Provides-Extra: mirascope
@@ -97,6 +101,8 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - ⚡ **Instant Notifications**: PostgreSQL LISTEN/NOTIFY for near-instant event delivery (optional)
 - 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
 - 🧠 **Mirascope Integration**: Durable LLM calls
+- 🦙 **LlamaIndex Integration**: Make LlamaIndex Workflows durable with crash recovery
+- 📊 **pydantic-graph Integration**: Durable graph-based workflows (experimental)
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
@@ -233,6 +239,12 @@ uv add edda-framework --extra viewer
 # With PostgreSQL instant notifications (LISTEN/NOTIFY)
 uv add edda-framework --extra postgres-notify
 
+# With LlamaIndex Workflow integration
+uv add edda-framework --extra llamaindex
+
+# With pydantic-graph integration (experimental)
+uv add edda-framework --extra graph
+
 # All extras (PostgreSQL, MySQL, Viewer UI)
 uv add edda-framework --extra postgresql --extra mysql --extra viewer
 ```

{edda_framework-0.14.1.dist-info → edda_framework-0.15.0.dist-info}/RECORD

@@ -13,6 +13,15 @@ edda/retry.py,sha256=t4_E1skrhotA1XWHTLbKi-DOgCMasOUnhI9OT-O_eCE,6843
 edda/workflow.py,sha256=hfBZM0JrtK0IkvZSrva0VmYVyvKCdiJ5FWFmIVENfrM,8807
 edda/wsgi.py,sha256=1pGE5fhHpcsYnDR8S3NEFKWUs5P0JK4roTAzX9BsIj0,2391
 edda/integrations/__init__.py,sha256=F_CaTvlDEbldfOpPKq_U9ve1E573tS6XzqXnOtyHcXI,33
+edda/integrations/graph/__init__.py,sha256=MwGgkTDsOH1eaLYzWFxBR2DHumiSAz-UUsqXSNU8aWw,1652
+edda/integrations/graph/context.py,sha256=ZQaesBVDAmF01P1liX2BtxaprQDRUgLKL0e94P8Yrdc,2529
+edda/integrations/graph/exceptions.py,sha256=FwDNUafYHzWlPeObLLTjyOVj8M94HgZ2a3DLR6VcOj4,286
+edda/integrations/graph/graph.py,sha256=RY3BbCUO_rsqQ2wP7ghfstT59stC_KNyJ7LmvljJSFk,12957
+edda/integrations/graph/nodes.py,sha256=JHoJYCEAGBKTYJ-458pMYvVxEu9hunAzzEuNVcEBbvM,4746
+edda/integrations/llamaindex/__init__.py,sha256=YR1ikaf7AanaQztGZfHDZtoMqz3ieTGjBeIQ3sAkzP8,1604
+edda/integrations/llamaindex/events.py,sha256=brs0UVu3kM5N9mWKo91FNBBh3FL9xI2WEzgHmp-j4a8,4751
+edda/integrations/llamaindex/exceptions.py,sha256=41BefzhS1qd2L1U-JHBNIkTQS_Vz480OATqOtJNmDGU,376
+edda/integrations/llamaindex/workflow.py,sha256=MXvPe8d7FLivCLoDlzQA-TgQi82nulUmW0omasq4QEk,10813
 edda/integrations/mcp/__init__.py,sha256=YK-8m0DIdP-RSqewlIX7xnWU7TD3NioCiW2_aZSgnn8,1232
 edda/integrations/mcp/decorators.py,sha256=31SmbDwmHEGvUNa3aaatW91hBkpnS5iN9uy47dID3J4,10037
 edda/integrations/mcp/server.py,sha256=Q5r4AbMn-9gBcy2CZocbgW7O0fn7Qb4e9CBJa1FEmzU,14507
@@ -47,8 +56,8 @@ edda/visualizer/mermaid_generator.py,sha256=XWa2egoOTNDfJEjPcwoxwQmblUqXf7YInWFj
 edda/migrations/mysql/20251217000000_initial_schema.sql,sha256=LpINasESRhadOeqABwDk4JZ0OZ4_zQw_opnhIR4Xe9U,12367
 edda/migrations/postgresql/20251217000000_initial_schema.sql,sha256=hCaGMWeptpzpnsjfNKVsMYuwPRe__fK9E0VZpClAumQ,11732
 edda/migrations/sqlite/20251217000000_initial_schema.sql,sha256=Wq9gCnQ0K9SOt0PY_8f1MG4va8rLVWIIcf2lnRzSK5g,11906
-edda_framework-0.14.1.dist-info/METADATA,sha256=3WamC1lB2LrLdUIbOPrYeoWsqW8leTXF8zRFB8rObpY,37567
-edda_framework-0.14.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-edda_framework-0.14.1.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
-edda_framework-0.14.1.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
-edda_framework-0.14.1.dist-info/RECORD,,
+edda_framework-0.15.0.dist-info/METADATA,sha256=d7VXuP5MWTx0WvL4KzwmZVl0AUtTJzTxaLWL7Q0Ou8Q,38074
+edda_framework-0.15.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+edda_framework-0.15.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
+edda_framework-0.15.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
+edda_framework-0.15.0.dist-info/RECORD,,