edda-framework 0.6.0__tar.gz → 0.7.0__tar.gz

{edda_framework-0.6.0 → edda_framework-0.7.0}/.gitignore

@@ -99,3 +99,4 @@ site/
 
 # Cache directories
 .cache/
+.nicegui/

{edda_framework-0.6.0 → edda_framework-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.6.0
+Version: 0.7.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -30,11 +30,13 @@ Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: uvloop>=0.22.1
 Provides-Extra: dev
 Requires-Dist: black>=25.9.0; extra == 'dev'
+Requires-Dist: mcp>=1.22.0; extra == 'dev'
 Requires-Dist: mypy>=1.18.2; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.2.0; extra == 'dev'
 Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
 Requires-Dist: pytest>=8.4.2; extra == 'dev'
 Requires-Dist: ruff>=0.14.2; extra == 'dev'
+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'

{edda_framework-0.6.0 → edda_framework-0.7.0}/docs/index.md

@@ -46,6 +46,7 @@ Edda's waiting functions make it ideal for time-based and event-driven business
 - **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
 
 **Waiting functions**:
+
 - `wait_timer(duration_seconds)`: Wait for a relative duration
 - `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
 - `wait_event(event_type)`: Wait for external events (near real-time response)

{edda_framework-0.6.0 → edda_framework-0.7.0}/docs/integrations/mcp.md

@@ -133,6 +133,7 @@ Output: {
 ```
 
 The status tool provides progress metadata for efficient polling:
+
 - **Completed Activities**: Number of activities that have finished
 - **Suggested Poll Interval**: Recommended wait time before checking again (5000ms for running, 10000ms for waiting)
 
@@ -169,6 +170,7 @@ Output: {
 ```
 
 The cancel tool:
+
 - Only works on workflows with status `running`, `waiting_for_event`, or `waiting_for_timer`
 - Automatically executes SAGA compensation transactions to roll back side effects
 - Returns an error for already completed, failed, or cancelled workflows

{edda_framework-0.6.0 → edda_framework-0.7.0}/docs/integrations/opentelemetry.md

@@ -76,11 +76,13 @@ workflow:order_workflow (parent)
 ## Span Attributes
 
 **Workflow Spans**:
+
 - `edda.workflow.instance_id`
 - `edda.workflow.name`
 - `edda.workflow.cancelled` (when cancelled)
 
 **Activity Spans**:
+
 - `edda.activity.id` (e.g., "reserve_inventory:1")
 - `edda.activity.name`
 - `edda.activity.is_replaying`
@@ -107,10 +109,12 @@ When `enable_metrics=True`:
 OpenTelemetryHooks automatically inherits trace context from multiple sources, with the following priority:
 
 1. **Explicit `_trace_context` in input_data** (highest priority)
+
    - Extracted from CloudEvents extension attributes
    - Useful for cross-service trace propagation
 
 2. **Current active span** (e.g., from ASGI/WSGI middleware)
+
    - Automatically detected using `trace.get_current_span()`
    - Works with OpenTelemetry instrumentation middleware
 

{edda_framework-0.6.0 → edda_framework-0.7.0}/docs/viewer-ui/setup.md

@@ -44,6 +44,16 @@ Then open http://localhost:8080 in your browser.
 
 *The Viewer UI shows all workflow instances with status badges and action buttons*
 
+**Pydantic Form Generation:**
+
+![Pydantic Form Generation](images/start-workflow-form-pydantic.png)
+
+*Auto-generated form fields based on Pydantic model type hints (str, float, int)*
+
+![Workflow Selection](images/workflow-selection-dropdown.png)
+
+*Dropdown showing all registered workflows with event_handler=True*
+
 ## Three Ways to Run the Viewer
 
 ### Method 1: Command Line (Recommended)
@@ -295,7 +305,7 @@ lsof -ti:8080 | xargs kill -9
 
 Once workflows appear, you'll see them with color-coded status badges:
 
-![Status Badges Example](images/status-badges-example.png)
+![Status Badges Example](images/workflow-list-view.png)
 
 *Workflow instances displayed with status badges (Completed ✅, Running ⏳, Failed ❌, Waiting ⏸️, Cancelled 🚫, etc.)*
 

{edda_framework-0.6.0 → edda_framework-0.7.0}/docs/viewer-ui/visualization.md

@@ -34,15 +34,22 @@ The Edda Viewer UI provides workflow visualization and monitoring.
 
 Workflows with conditional logic (if/else, match/case) are visualized with labeled branches:
 
-![Conditional Branching Diagram](images/conditional-branching-diagram.png)
+![Workflow Detail Page](images/detail-page-loan-approval.png)
 
-*Example: `loan_approval_workflow` showing conditional branches based on credit score ("sufficient" vs "insufficient" paths)*
+*Example: `loan_approval_workflow` detail page. Note the **Execution Flow diagram** (bottom left) showing conditional branches with "sufficient" vs "insufficient" paths based on credit score.*
 
 The diagram clearly shows:
+
 - Decision points (diamond shapes in some diagrams)
 - Branch labels indicating conditions
 - Different execution paths based on runtime data
 
+**Match/Case Pattern:**
+
+![Match Case Workflow](images/detail-page-match-case.png)
+
+*Example: `match_case_workflow` showing multiple case branches with different handlers*
+
 ## Viewing Workflows
 
 ### Workflow List
@@ -68,42 +75,46 @@ The main page shows all workflow instances:
 - 🚫 **Cancelled**: Manually cancelled (orange)
 - 🔄 **Compensating**: Executing compensations (purple)
 
-![Status Badges Example](images/status-badges-example.png)
+![Status Badges Example](images/workflow-list-view.png)
 
 ### Workflow List View
 
-The main page displays workflow instances as interactive cards:
+The main page displays workflow instances as interactive cards with search and filter capabilities:
 
 ![Workflow List View](images/workflow-list-view.png)
 
+*Workflow list with search filter bar, status filter, date range picker, and pagination controls*
+
 ### Workflow Detail Page
 
-Click on a workflow instance to see:
+Click on a workflow instance to see the detail page:
+
+![Workflow Detail Page](images/detail-page-loan-approval.png)
 
-1. **Overview Panel**:
-   - Instance ID, status, timestamps
-   - Input parameters (JSON)
-   - Output result (if completed)
+*Workflow detail page showing the Overview Panel (top), Execution Flow diagram (bottom left), and Activity Details panel (bottom right).*
 
-![Workflow Detail - Overview Panel](images/detail-overview-panel.png)
+1. **Overview Panel** (top):
 
-2. **Hybrid Diagram**:
-   - Visual graph of workflow structure
-   - Color-coded execution status
-   - Compensation flow (if applicable)
+      - Instance ID, status, timestamps
+      - Input parameters (JSON)
+      - Output result (if completed)
 
-![Hybrid Diagram Example](images/hybrid-diagram-example.png)
+2. **Execution Flow** (bottom left):
 
-3. **Execution History**:
-   - Step-by-step execution log
-   - Activity results
-   - Event data (for wait_event)
-   - Error messages (if failed)
+      - Visual graph of workflow structure
+      - Color-coded execution status
+      - Compensation flow (if applicable)
 
-![Execution History Panel](images/execution-history-panel.png)
+3. **Activity Details** (bottom right):
+
+      - Step-by-step execution log
+      - Activity results
+      - Event data (for wait_event)
+      - Error messages (if failed)
 
 4. **Actions**:
-   - **Cancel**: Stop running workflow
+
+      - **Cancel**: Stop running workflow
 
 ## Starting Workflows from Viewer
 
@@ -113,21 +124,15 @@ The Viewer UI can start workflows with automatic form generation:
 
 For Pydantic-based workflows, the Viewer generates input forms automatically.
 
-![Start Workflow Dialog](images/start-workflow-dialog.png)
+![Start Workflow Dialog](images/workflow-selection-dropdown.png)
 
-*Example: Workflow selection with auto-generated form*
+*Example: Workflow selection dropdown showing all registered workflows*
 
 The form generator supports various field types based on Pydantic model definitions:
 
-![Form Generation Example](images/form-generation-example.png)
-
-*Example: Auto-generated form showing different field types (text inputs, number inputs, checkboxes, etc.)*
-
-For complex workflows with nested models:
-
 ![Nested Pydantic Form](images/nested-pydantic-form.png)
 
-*Example: Auto-generated form with nested Pydantic models (OrderItem list, ShippingAddress)*
+*Auto-generated form with nested Pydantic models (items list, shipping_address) showing text inputs, number inputs, and nested model containers*
 
 ### Starting Workflow
 
@@ -166,7 +171,7 @@ When a workflow is cancelled or fails, and compensations run, the diagram shows:
 
 ![Compensation Execution](images/compensation-execution.png)
 
-*Example: `cancellable_booking` workflow after cancellation*
+*Saga compensation flow showing rollback activities (cancel_flight_ticket, cancel_hotel_room)*
 
 ## Event Waiting Visualization
 
@@ -174,7 +179,7 @@ Workflows can wait for external events using `wait_event()`. The Viewer displays
 
 ![Event Waiting Visualization](images/wait-event-visualization.png)
 
-*Example: `payment_workflow` waiting for `payment.completed` event*
+*Workflow with wait_event showing event type, timeout, and activity details panel*
 
 The diagram shows:
 - Hexagon node: Event wait point

{edda_framework-0.6.0 → edda_framework-0.7.0}/edda/storage/protocol.py

@@ -238,20 +238,34 @@ class StorageProtocol(Protocol):
     async def list_instances(
         self,
         limit: int = 50,
+        page_token: str | None = None,
         status_filter: str | None = None,
-    ) -> list[dict[str, Any]]:
+        workflow_name_filter: str | None = None,
+        instance_id_filter: str | None = None,
+        started_after: datetime | None = None,
+        started_before: datetime | None = None,
+    ) -> dict[str, Any]:
         """
-        List workflow instances with optional filtering.
+        List workflow instances with cursor-based pagination and filtering.
 
         This method JOINs workflow_instances with workflow_definitions to
         return instances along with their source code.
 
         Args:
-            limit: Maximum number of instances to return
+            limit: Maximum number of instances to return per page
+            page_token: Cursor for pagination (format: "ISO_DATETIME||INSTANCE_ID")
             status_filter: Optional status filter (e.g., "running", "completed", "failed")
+            workflow_name_filter: Optional workflow name filter (partial match, case-insensitive)
+            instance_id_filter: Optional instance ID filter (partial match, case-insensitive)
+            started_after: Filter instances started after this datetime (inclusive)
+            started_before: Filter instances started before this datetime (inclusive)
 
         Returns:
-            List of workflow instances, ordered by started_at DESC.
+            Dictionary containing:
+            - instances: List of workflow instances, ordered by started_at DESC
+            - next_page_token: Cursor for the next page, or None if no more pages
+            - has_more: Boolean indicating if there are more pages
+
             Each instance contains: instance_id, workflow_name, source_hash,
             owner_service, status, current_activity_id, started_at, updated_at,
             input_data, source_code, output_data, locked_by, locked_at

{edda_framework-0.6.0 → edda_framework-0.7.0}/edda/storage/sqlalchemy_storage.py

@@ -774,11 +774,17 @@ class SQLAlchemyStorage:
     async def list_instances(
         self,
         limit: int = 50,
+        page_token: str | None = None,
         status_filter: str | None = None,
-    ) -> list[dict[str, Any]]:
-        """List workflow instances with optional filtering."""
+        workflow_name_filter: str | None = None,
+        instance_id_filter: str | None = None,
+        started_after: datetime | None = None,
+        started_before: datetime | None = None,
+    ) -> dict[str, Any]:
+        """List workflow instances with cursor-based pagination and filtering."""
         session = self._get_session_for_operation()
         async with self._session_scope(session) as session:
+            # Base query with JOIN
             stmt = (
                 select(WorkflowInstance, WorkflowDefinition.source_code)
                 .join(
@@ -788,17 +794,105 @@ class SQLAlchemyStorage:
                         WorkflowInstance.source_hash == WorkflowDefinition.source_hash,
                     ),
                 )
-                .order_by(WorkflowInstance.started_at.desc())
-                .limit(limit)
+                .order_by(
+                    WorkflowInstance.started_at.desc(),
+                    WorkflowInstance.instance_id.desc(),
+                )
             )
 
+            # Apply cursor-based pagination (page_token format: "ISO_DATETIME||INSTANCE_ID")
+            if page_token:
+                # Parse page_token: || separates datetime and instance_id
+                separator = "||"
+                if separator in page_token:
+                    cursor_time_str, cursor_id = page_token.split(separator, 1)
+                    cursor_time = datetime.fromisoformat(cursor_time_str)
+                    # Use _make_datetime_comparable for SQLite compatibility
+                    started_at_comparable = self._make_datetime_comparable(
+                        WorkflowInstance.started_at
+                    )
+                    # For SQLite, also wrap the cursor_time in func.datetime()
+                    cursor_time_comparable: Any
+                    if self.engine.dialect.name == "sqlite":
+                        cursor_time_comparable = func.datetime(cursor_time_str)
+                    else:
+                        cursor_time_comparable = cursor_time
+                    # For DESC order, we want rows where (started_at, instance_id) < cursor
+                    stmt = stmt.where(
+                        or_(
+                            started_at_comparable < cursor_time_comparable,
+                            and_(
+                                started_at_comparable == cursor_time_comparable,
+                                WorkflowInstance.instance_id < cursor_id,
+                            ),
+                        )
+                    )
+
+            # Apply status filter
             if status_filter:
                 stmt = stmt.where(WorkflowInstance.status == status_filter)
 
+            # Apply workflow name and/or instance ID filter (partial match, case-insensitive)
+            # When both filters have the same value (unified search), use OR logic
+            if workflow_name_filter and instance_id_filter:
+                if workflow_name_filter == instance_id_filter:
+                    # Unified search: match either workflow name OR instance ID
+                    stmt = stmt.where(
+                        or_(
+                            WorkflowInstance.workflow_name.ilike(f"%{workflow_name_filter}%"),
+                            WorkflowInstance.instance_id.ilike(f"%{instance_id_filter}%"),
+                        )
+                    )
+                else:
+                    # Separate filters: match both (AND logic)
+                    stmt = stmt.where(
+                        WorkflowInstance.workflow_name.ilike(f"%{workflow_name_filter}%")
+                    )
+                    stmt = stmt.where(WorkflowInstance.instance_id.ilike(f"%{instance_id_filter}%"))
+            elif workflow_name_filter:
+                stmt = stmt.where(WorkflowInstance.workflow_name.ilike(f"%{workflow_name_filter}%"))
+            elif instance_id_filter:
+                stmt = stmt.where(WorkflowInstance.instance_id.ilike(f"%{instance_id_filter}%"))
+
+            # Apply date range filters (use _make_datetime_comparable for SQLite)
+            if started_after or started_before:
+                started_at_comparable = self._make_datetime_comparable(WorkflowInstance.started_at)
+                if started_after:
+                    started_after_comparable: Any
+                    if self.engine.dialect.name == "sqlite":
+                        started_after_comparable = func.datetime(started_after.isoformat())
+                    else:
+                        started_after_comparable = started_after
+                    stmt = stmt.where(started_at_comparable >= started_after_comparable)
+                if started_before:
+                    started_before_comparable: Any
+                    if self.engine.dialect.name == "sqlite":
+                        started_before_comparable = func.datetime(started_before.isoformat())
+                    else:
+                        started_before_comparable = started_before
+                    stmt = stmt.where(started_at_comparable <= started_before_comparable)
+
+            # Fetch limit+1 to determine if there are more pages
+            stmt = stmt.limit(limit + 1)
+
             result = await session.execute(stmt)
             rows = result.all()
 
-            return [
+            # Determine has_more and next_page_token
+            has_more = len(rows) > limit
+            if has_more:
+                rows = rows[:limit]  # Trim to actual limit
+
+            # Generate next_page_token from last row
+            next_page_token: str | None = None
+            if has_more and rows:
+                last_instance = rows[-1][0]
+                # Format: ISO_DATETIME||INSTANCE_ID (using || as separator)
+                next_page_token = (
+                    f"{last_instance.started_at.isoformat()}||{last_instance.instance_id}"
+                )
+
+            instances = [
                 {
                     "instance_id": instance.instance_id,
                     "workflow_name": instance.workflow_name,
@@ -820,6 +914,12 @@ class SQLAlchemyStorage:
                 for instance, source_code in rows
             ]
 
+            return {
+                "instances": instances,
+                "next_page_token": next_page_token,
+                "has_more": has_more,
+            }
+
     # -------------------------------------------------------------------------
     # Distributed Locking Methods (ALWAYS use separate session/transaction)
     # -------------------------------------------------------------------------