edda-framework 0.14.1__tar.gz → 0.15.0__tar.gz

{edda_framework-0.14.1 → edda_framework-0.15.0}/PKG-INFO

@@ -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 → edda_framework-0.15.0}/README.md

@@ -32,6 +32,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
@@ -168,6 +170,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.15.0/docs/integrations/llamaindex.md

@@ -0,0 +1,213 @@
+# LlamaIndex Workflow Integration
+
+Edda provides integration with [LlamaIndex Workflow](https://docs.llamaindex.ai/en/stable/module_guides/workflow/), making your LlamaIndex Workflows **durable**. Each workflow step is automatically recorded as an Edda Activity, enabling crash recovery and deterministic replay.
+
+## Overview
+
+LlamaIndex Workflow is an event-driven orchestration framework for building complex AI pipelines. Edda's integration adds:
+
+- **Crash Recovery**: If your workflow crashes, completed steps are replayed from cache
+- **Durable Timers**: Use `DurableSleepEvent` for timers that survive crashes
+- **Durable Event Waiting**: Use `DurableWaitEvent` to wait for external events durably
+- **Step-level Durability**: Each `@step` becomes a durable Edda Activity
+
+## Installation
+
+```bash
+pip install 'edda-framework[llamaindex]'
+
+# Or using uv
+uv add edda-framework --extra llamaindex
+```
+
+## Quick Start
+
+```python
+from llama_index.core.workflow import Workflow, step, StartEvent, StopEvent, Event
+from edda import EddaApp, workflow, WorkflowContext
+from edda.integrations.llamaindex import DurableWorkflowRunner
+
+# Define events
+class OrderReceivedEvent(Event):
+    order_id: str
+    amount: float
+
+class ProcessingCompleteEvent(Event):
+    order_id: str
+    status: str
+
+# Define LlamaIndex Workflow
+class OrderWorkflow(Workflow):
+    @step
+    async def receive_order(self, ctx, ev: StartEvent) -> OrderReceivedEvent:
+        print(f"Received order: {ev.order_id}")
+        return OrderReceivedEvent(order_id=ev.order_id, amount=ev.amount)
+
+    @step
+    async def process_order(self, ctx, ev: OrderReceivedEvent) -> ProcessingCompleteEvent:
+        print(f"Processing order {ev.order_id}...")
+        return ProcessingCompleteEvent(order_id=ev.order_id, status="processed")
+
+    @step
+    async def complete_order(self, ctx, ev: ProcessingCompleteEvent) -> StopEvent:
+        return StopEvent(result={
+            "order_id": ev.order_id,
+            "status": ev.status,
+            "message": "Order completed successfully",
+        })
+
+# Create durable runner
+runner = DurableWorkflowRunner(OrderWorkflow)
+
+# Wrap in Edda workflow
+@workflow
+async def order_workflow(ctx: WorkflowContext, order_id: str, amount: float) -> dict:
+    result = await runner.run(ctx, order_id=order_id, amount=amount)
+    return result
+
+# Run the workflow
+async def main():
+    app = EddaApp(service_name="order-service", db_url="sqlite:///app.db")
+    await app.initialize()
+
+    instance_id = await order_workflow.start(order_id="ORD-001", amount=99.99)
+    print(f"Started workflow: {instance_id}")
+
+    await app.shutdown()
+```
+
+## How It Works
+
+```
+LlamaIndex Workflow Steps
+        │
+        ▼
+┌──────────────────────┐
+│ DurableWorkflowRunner│  ← Wraps your Workflow class
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│   For each @step:    │
+│   - Serialize event  │
+│   - Run as Activity  │
+│   - Deserialize result│
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│   Edda @activity     │  ← Each step is durable
+│   (_run_step)        │
+└──────────────────────┘
+```
+
+**On Replay**: If the workflow crashes and restarts, completed steps return cached results from the Edda history. Steps are not re-executed.
+
+## Durable Sleep
+
+Use `DurableSleepEvent` for timers that survive crashes:
+
+```python
+from edda.integrations.llamaindex import DurableSleepEvent
+
+class RateLimitedWorkflow(Workflow):
+    @step
+    async def check_rate_limit(self, ctx, ev: StartEvent) -> DurableSleepEvent | ProcessEvent:
+        if is_rate_limited():
+            # Sleep for 60 seconds (durable timer)
+            return DurableSleepEvent(
+                seconds=60,
+                resume_data={"retry_count": ev.retry_count + 1}
+            )
+        return ProcessEvent(data=ev.data)
+
+    @step
+    async def handle_resume(self, ctx, ev: ResumeEvent) -> ProcessEvent:
+        # Called after DurableSleepEvent completes
+        retry_count = ev.data.get("retry_count", 0)
+        return ProcessEvent(data={"retried": retry_count})
+```
+
+## Durable Wait for External Events
+
+Use `DurableWaitEvent` to wait for external events:
+
+```python
+from edda.integrations.llamaindex import DurableWaitEvent, ResumeEvent
+
+class ApprovalWorkflow(Workflow):
+    @step
+    async def request_approval(self, ctx, ev: StartEvent) -> DurableWaitEvent:
+        # Wait for approval event (up to 1 hour)
+        return DurableWaitEvent(
+            event_type=f"approval.{ev.request_id}",
+            timeout_seconds=3600,
+        )
+
+    @step
+    async def process_approval(self, ctx, ev: ResumeEvent) -> StopEvent:
+        # Called when external event arrives
+        approved = ev.data.get("approved", False)
+        return StopEvent(result={"approved": approved})
+```
+
+To send the external event:
+
+```python
+from edda import send_event
+
+await send_event(
+    event_type="approval.REQ-123",
+    source="approval-service",
+    data={"approved": True},
+)
+```
+
+## API Reference
+
+### DurableWorkflowRunner
+
+```python
+from edda.integrations.llamaindex import DurableWorkflowRunner
+
+runner = DurableWorkflowRunner(MyWorkflow)
+result = await runner.run(ctx, **start_event_kwargs)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `workflow_class` | `type[Workflow]` | LlamaIndex Workflow class (not instance) |
+
+### DurableSleepEvent
+
+```python
+DurableSleepEvent(
+    seconds: float,           # Duration to sleep
+    resume_data: dict = None, # Data passed to ResumeEvent
+)
+```
+
+### DurableWaitEvent
+
+```python
+DurableWaitEvent(
+    event_type: str,              # Event type to wait for
+    timeout_seconds: float = None, # Optional timeout
+)
+```
+
+### ResumeEvent
+
+Returned after `DurableSleepEvent` or `DurableWaitEvent` completes:
+
+```python
+class ResumeEvent:
+    data: dict  # Contains resume_data or received event data
+```
+
+## Related Documentation
+
+- [Workflows and Activities](../core-features/workflows-activities.md) - Core concepts of durable execution
+- [Event Waiting](../core-features/events/wait-event.md) - wait_event() function
+- [LlamaIndex Workflow Docs](https://docs.llamaindex.ai/en/stable/module_guides/workflow/) - Official LlamaIndex documentation
+- [Examples](https://github.com/i2y/edda/tree/main/examples/llamaindex) - Complete working examples

edda_framework-0.15.0/docs/integrations/pydantic-graph.md

@@ -0,0 +1,256 @@
+# pydantic-graph Integration (Experimental)
+
+> **Status: Experimental**
+> This integration is functional but has known limitations with type hints. The API may change in future versions.
+
+Edda provides integration with [pydantic-graph](https://ai.pydantic.dev/pydantic-graph/), making graph-based workflows **durable**. Each node execution is automatically recorded as an Edda Activity, enabling crash recovery and deterministic replay.
+
+## Overview
+
+pydantic-graph is a graph-based workflow library that uses dataclass nodes and type-safe transitions. Edda's integration adds:
+
+- **Crash Recovery**: If your workflow crashes, completed nodes are replayed from cache
+- **Durable Timers**: Use `Sleep` marker for timers that survive crashes
+- **Durable Event Waiting**: Use `WaitForEvent` marker to wait for external events durably
+- **Node-level Durability**: Each node execution becomes a durable Edda Activity
+
+## Known Limitations
+
+**Type hint limitation**: The `Sleep` and `WaitForEvent` markers cannot be included in node return type annotations due to pydantic-graph's strict type validation. You need to use `# type: ignore` comments:
+
+```python
+# This works at runtime but requires type: ignore
+async def run(self, ctx: DurableGraphContext) -> "NextNode":  # type: ignore[override]
+    return Sleep(seconds=60, next_node=NextNode())
+```
+
+If you need clean type hints for graph visualization, consider the [LlamaIndex Workflow integration](./llamaindex.md) instead.
+
+## Installation
+
+```bash
+pip install 'edda-framework[graph]'
+
+# Or using uv
+uv add edda-framework --extra graph
+```
+
+## Quick Start
+
+```python
+from dataclasses import dataclass
+from pydantic_graph import BaseNode, End, Graph
+from edda import EddaApp, workflow, WorkflowContext
+from edda.integrations.graph import DurableGraph, DurableGraphContext
+
+# Define state
+@dataclass
+class OrderState:
+    order_id: str | None = None
+    total: float = 0.0
+    status: str = "pending"
+
+# Define nodes
+@dataclass
+class ValidateOrderNode(BaseNode[OrderState, None, dict]):
+    order_id: str
+    amount: float
+
+    async def run(self, ctx: DurableGraphContext) -> "ProcessPaymentNode":
+        ctx.state.order_id = self.order_id
+        ctx.state.total = self.amount
+        ctx.state.status = "validated"
+        return ProcessPaymentNode()
+
+@dataclass
+class ProcessPaymentNode(BaseNode[OrderState, None, dict]):
+    async def run(self, ctx: DurableGraphContext) -> End[dict]:
+        ctx.state.status = "paid"
+        return End({
+            "order_id": ctx.state.order_id,
+            "total": ctx.state.total,
+            "status": ctx.state.status,
+        })
+
+# Create graph and durable wrapper
+graph = Graph(nodes=[ValidateOrderNode, ProcessPaymentNode])
+durable_graph = DurableGraph(graph)
+
+# Wrap in Edda workflow
+@workflow
+async def order_workflow(ctx: WorkflowContext, order_id: str, amount: float) -> dict:
+    return await durable_graph.run(
+        ctx,
+        start_node=ValidateOrderNode(order_id=order_id, amount=amount),
+        state=OrderState(),
+    )
+
+# Run the workflow
+async def main():
+    app = EddaApp(service_name="order-service", db_url="sqlite:///app.db")
+    await app.initialize()
+
+    instance_id = await order_workflow.start(order_id="ORD-001", amount=99.99)
+    print(f"Started workflow: {instance_id}")
+
+    await app.shutdown()
+```
+
+## How It Works
+
+```
+pydantic-graph Nodes
+        │
+        ▼
+┌──────────────────────┐
+│    DurableGraph      │  ← Wraps your Graph
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│   For each node:     │
+│   - Serialize state  │
+│   - Run as Activity  │
+│   - Deserialize result│
+└──────────┬───────────┘
+           │
+           ▼
+┌──────────────────────┐
+│   Edda @activity     │  ← Each node is durable
+│   (_run_graph_node)  │
+└──────────────────────┘
+```
+
+**On Replay**: If the workflow crashes and restarts, completed nodes return cached results from the Edda history. Nodes are not re-executed.
+
+## Durable Sleep
+
+Use the `Sleep` marker for timers that survive crashes:
+
+```python
+from edda.integrations.graph import Sleep
+
+@dataclass
+class RateLimitNode(BaseNode[MyState, None, str]):
+    async def run(self, ctx: DurableGraphContext) -> "RetryNode":  # type: ignore[override]
+        if is_rate_limited():
+            # Sleep for 60 seconds (durable timer)
+            return Sleep(seconds=60, next_node=RetryNode())
+        return RetryNode()
+```
+
+## Durable Wait for External Events
+
+Use the `WaitForEvent` marker to wait for external events:
+
+```python
+from edda.integrations.graph import WaitForEvent, ReceivedEvent
+
+@dataclass
+class WaitForApprovalNode(BaseNode[OrderState, None, str]):
+    async def run(self, ctx: DurableGraphContext) -> "ProcessApprovalNode":  # type: ignore[override]
+        return WaitForEvent(
+            event_type=f"approval.{ctx.state.order_id}",
+            next_node=ProcessApprovalNode(),
+            timeout_seconds=3600,
+        )
+
+@dataclass
+class ProcessApprovalNode(BaseNode[OrderState, None, str]):
+    async def run(self, ctx: DurableGraphContext) -> End[str]:
+        # Access the received event via ctx.last_event
+        event: ReceivedEvent = ctx.last_event
+        if event.data.get("approved"):
+            return End("approved")
+        return End("rejected")
+```
+
+To send the external event:
+
+```python
+from edda import send_event
+
+await send_event(
+    event_type="approval.ORD-123",
+    source="approval-service",
+    data={"approved": True},
+)
+```
+
+## DurableGraphContext
+
+The `DurableGraphContext` provides access to state, dependencies, and received events:
+
+```python
+@dataclass
+class MyNode(BaseNode[MyState, MyDeps, str]):
+    async def run(self, ctx: DurableGraphContext) -> End[str]:
+        # Access state (mutable)
+        ctx.state.counter += 1
+
+        # Access dependencies (read-only)
+        api_key = ctx.deps.api_key
+
+        # Access last received event (after WaitForEvent)
+        if ctx.last_event:
+            data = ctx.last_event.data
+
+        # Access Edda WorkflowContext for advanced operations
+        edda_ctx = ctx.workflow_ctx
+
+        return End("done")
+```
+
+## API Reference
+
+### DurableGraph
+
+```python
+from edda.integrations.graph import DurableGraph
+
+durable = DurableGraph(graph)
+result = await durable.run(ctx, start_node=MyNode(), state=MyState(), deps=MyDeps())
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `graph` | `Graph` | pydantic-graph Graph instance |
+
+### Sleep
+
+```python
+Sleep(
+    seconds: int,      # Duration to sleep
+    next_node: NextT,  # Node to continue with after sleep
+)
+```
+
+### WaitForEvent
+
+```python
+WaitForEvent(
+    event_type: str,               # Event type to wait for
+    next_node: NextT,              # Node to continue with after event
+    timeout_seconds: int | None,   # Optional timeout
+)
+```
+
+### ReceivedEvent
+
+Available via `ctx.last_event` after `WaitForEvent` completes:
+
+```python
+@dataclass
+class ReceivedEvent:
+    event_type: str              # The event type that was received
+    data: dict[str, Any]         # Event payload
+    metadata: dict[str, Any]     # Event metadata
+```
+
+## Related Documentation
+
+- [Workflows and Activities](../core-features/workflows-activities.md) - Core concepts of durable execution
+- [Event Waiting](../core-features/events/wait-event.md) - wait_event() function
+- [LlamaIndex Integration](./llamaindex.md) - Alternative with better type hint support
+- [pydantic-graph Documentation](https://ai.pydantic.dev/pydantic-graph/) - Official pydantic-graph docs
+- [Examples](https://github.com/i2y/edda/tree/main/examples/graph) - Complete working examples

edda_framework-0.15.0/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_framework-0.15.0/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_framework-0.15.0/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)