loom-core 1.0.1__tar.gz → 1.0.2__tar.gz

{loom_core-1.0.1 → loom_core-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loom-core
-Version: 1.0.1
+Version: 1.0.2
 Summary: Durable workflow orchestration engine for Python
 Home-page: https://github.com/satadeep3927/loom
 Author: Satadeep Dasgupta

loom_core-1.0.2/loom/web/__init__.py

@@ -0,0 +1,5 @@
+"""Loom Web Dashboard Module
+
+This module provides a FastAPI-based web interface for monitoring and managing
+Loom workflows, including REST APIs and server-sent events for real-time updates.
+"""

loom_core-1.0.2/loom/web/api/__init__.py

@@ -0,0 +1,4 @@
+"""API Modules
+
+This package contains all API route handlers organized by resource type.
+"""

loom_core-1.0.2/loom/web/api/events.py

@@ -0,0 +1,315 @@
+"""Event API Endpoints
+
+Provides REST endpoints for querying workflow events across the system.
+"""
+
+import json
+import math
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import StreamingResponse
+
+from ...database.db import Database
+from ..schemas import (
+    ErrorResponse,
+    EventDetail,
+    EventListParams,
+    EventType,
+    PaginatedResponse,
+    PaginationMeta,
+    WorkflowStatus,
+)
+
+router = APIRouter()
+
+
+async def get_db():
+    """Database dependency"""
+    async with Database[Any, Any]() as db:
+        yield db
+
+
+@router.get(
+    "/",
+    response_model=PaginatedResponse[EventDetail],
+    summary="List events",
+    description="""
+    Retrieve a paginated list of events across all workflows with optional filtering.
+
+    **Filtering Options:**
+    - `workflow_id`: Filter by specific workflow
+    - `type`: Filter by event type (WORKFLOW_STARTED, STEP_START, etc.)
+    - `since`: Filter events after specified timestamp
+
+    **Sorting Options:**
+    - `sort_by`: Field to sort by (id, created_at)
+    - `sort_order`: Sort direction (asc/desc, default desc for recent-first)
+
+    **Pagination:**
+    - `page`: Page number (1-based)
+    - `per_page`: Items per page (1-1000, default 100)
+
+    **Use Cases:**
+    - System-wide event monitoring
+    - Debugging cross-workflow issues
+    - Audit trail and compliance reporting
+    """,
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid request parameters"},
+        500: {"model": ErrorResponse, "description": "Internal server error"},
+    },
+)
+async def list_events(
+    params: EventListParams = Depends(), db: Database = Depends(get_db)
+):
+    """List events with pagination and filtering"""
+    try:
+        # Build WHERE clause
+        where_conditions = []
+        query_params = []
+
+        if params.workflow_id:
+            where_conditions.append("e.workflow_id = ?")
+            query_params.append(params.workflow_id)
+
+        if params.type:
+            where_conditions.append("e.type = ?")
+            query_params.append(params.type.value)
+
+        if params.since:
+            where_conditions.append("e.created_at >= ?")
+            query_params.append(params.since.isoformat())
+
+        where_clause = (
+            f"WHERE {' AND '.join(where_conditions)}" if where_conditions else ""
+        )
+
+        # Get total count
+        count_sql = f"""
+            SELECT COUNT(*) as total
+            FROM events e
+            JOIN workflows w ON e.workflow_id = w.id
+            {where_clause}
+        """
+        count_result = await db.fetchone(count_sql, tuple(query_params))
+        total = count_result["total"] if count_result else 0
+
+        # Calculate pagination
+        pages = math.ceil(total / params.per_page) if total > 0 else 1
+        offset = (params.page - 1) * params.per_page
+
+        # Build ORDER BY clause
+        order_clause = f"ORDER BY e.{params.sort_by} {params.sort_order.upper()}"
+
+        # Get events for current page with workflow info
+        events_sql = f"""
+            SELECT
+                e.id,
+                e.workflow_id,
+                w.name as workflow_name,
+                w.status as workflow_status,
+                e.type,
+                e.payload,
+                e.created_at
+            FROM events e
+            JOIN workflows w ON e.workflow_id = w.id
+            {where_clause}
+            {order_clause}
+            LIMIT {params.per_page} OFFSET {offset}
+        """
+
+        events = await db.query(events_sql, tuple(query_params))
+
+        # Convert to response models
+        event_details = [
+            EventDetail(
+                id=e["id"],
+                workflow_id=e["workflow_id"],
+                workflow_name=e["workflow_name"],
+                workflow_status=WorkflowStatus(e["workflow_status"]),
+                type=EventType(e["type"]),
+                payload=json.loads(e["payload"]),
+                created_at=e["created_at"],
+            )
+            for e in events
+        ]
+
+        # Build pagination metadata
+        meta = PaginationMeta(
+            page=params.page,
+            per_page=params.per_page,
+            total=total,
+            pages=pages,
+            has_prev=params.page > 1,
+            has_next=params.page < pages,
+        )
+
+        return PaginatedResponse(data=event_details, meta=meta)
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to list events: {str(e)}")
+
+
+@router.get(
+    "/{event_id}",
+    response_model=EventDetail,
+    summary="Get event details",
+    description="""
+    Retrieve complete information for a specific event.
+
+    **Returns:**
+    - Complete event data including payload
+    - Parent workflow context and status
+    - Event timing information
+
+    **Use Cases:**
+    - Debug specific event handling
+    - Investigate event payload data
+    - Understand event context
+    """,
+    responses={
+        404: {"model": ErrorResponse, "description": "Event not found"},
+        500: {"model": ErrorResponse, "description": "Internal server error"},
+    },
+)
+async def get_event(event_id: int, db: Database = Depends(get_db)):
+    """Get detailed event information"""
+    try:
+        # Get event info with workflow context
+        event_sql = """
+            SELECT
+                e.id,
+                e.workflow_id,
+                w.name as workflow_name,
+                w.status as workflow_status,
+                e.type,
+                e.payload,
+                e.created_at
+            FROM events e
+            JOIN workflows w ON e.workflow_id = w.id
+            WHERE e.id = ?
+        """
+
+        event = await db.fetchone(event_sql, (event_id,))
+        if not event:
+            raise HTTPException(status_code=404, detail=f"Event {event_id} not found")
+
+        return EventDetail(
+            id=event["id"],
+            workflow_id=event["workflow_id"],
+            workflow_name=event["workflow_name"],
+            workflow_status=WorkflowStatus(event["workflow_status"]),
+            type=EventType(event["type"]),
+            payload=json.loads(event["payload"]),
+            created_at=event["created_at"],
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to get event: {str(e)}")
+
+
+@router.get(
+    "/stream",
+    summary="Stream all events (SSE)",
+    description="""
+    **Server-Sent Events stream for real-time system-wide event monitoring.**
+
+    This endpoint provides a persistent connection that streams new events
+    as they occur across all workflows in the system.
+
+    **Stream Format:**
+    ```
+    data: {"id": 123, "workflow_id": "abc", "type": "STEP_START", "payload": {...}}
+
+    data: {"id": 124, "workflow_id": "def", "type": "WORKFLOW_COMPLETED", "payload": {...}}
+    ```
+
+    **Usage (JavaScript):**
+    ```javascript
+    const eventSource = new EventSource('/api/events/stream');
+    eventSource.onmessage = function(event) {
+        const data = JSON.parse(event.data);
+        console.log('System event:', data);
+    };
+    ```
+
+    **Use Cases:**
+    - Real-time system monitoring dashboard
+    - Live activity feeds
+    - Event-driven UI updates
+    - System health monitoring
+    """,
+    responses={500: {"model": ErrorResponse, "description": "Internal server error"}},
+)
+async def stream_all_events(db: Database = Depends(get_db)):
+    """Stream all system events via Server-Sent Events"""
+    try:
+
+        async def event_stream():
+            import asyncio
+            import json
+
+            last_event_id = 0
+
+            # Get current max event ID to avoid replaying history
+            max_id_sql = "SELECT MAX(id) as max_id FROM events"
+            max_result = await db.fetchone(max_id_sql, ())
+            if max_result and max_result["max_id"]:
+                last_event_id = max_result["max_id"]
+
+            while True:
+                try:
+                    # Check for new events across all workflows
+                    events_sql = """
+                        SELECT
+                            e.id,
+                            e.workflow_id,
+                            w.name as workflow_name,
+                            e.type,
+                            e.payload,
+                            e.created_at
+                        FROM events e
+                        JOIN workflows w ON e.workflow_id = w.id
+                        WHERE e.id > ?
+                        ORDER BY e.id ASC
+                        LIMIT 100
+                    """
+                    new_events = await db.query(events_sql, (last_event_id,))
+
+                    for event in new_events:
+                        event_data = {
+                            "id": event["id"],
+                            "workflow_id": event["workflow_id"],
+                            "workflow_name": event["workflow_name"],
+                            "type": event["type"],
+                            "payload": json.loads(event["payload"]),
+                            "created_at": event["created_at"],
+                        }
+                        yield f"data: {json.dumps(event_data)}\n\n"
+                        last_event_id = event["id"]
+
+                    # Poll every second
+                    await asyncio.sleep(1)
+
+                except Exception as e:
+                    yield f"data: {json.dumps({'error': str(e)})}\n\n"
+                    # Don't break on errors, continue polling
+                    await asyncio.sleep(5)
+
+        return StreamingResponse(
+            event_stream(),
+            media_type="text/plain",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "Content-Type": "text/event-stream",
+            },
+        )
+
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to stream events: {str(e)}"
+        )

loom_core-1.0.2/loom/web/api/graphs.py

@@ -0,0 +1,236 @@
+"""Graph API Endpoints
+
+Provides REST endpoints for generating workflow definition graphs.
+"""
+
+from typing import Any, Dict
+from fastapi import APIRouter, HTTPException, Query, Depends
+from enum import Enum
+
+from ...core.graph import WorkflowAnalyzer, generate_mermaid_graph, generate_graphviz_dot
+from ...common.workflow import workflow_registry
+from ...database.db import Database
+from ..schemas import ErrorResponse
+from ...schemas.graph import WorkflowDefinitionGraph, GraphResponse, GraphFormat
+
+router = APIRouter()
+
+
+async def get_db():
+    """Database dependency"""
+    async with Database[Any, Any]() as db:
+        yield db
+
+
+class GraphFormatEnum(str, Enum):
+    """Supported graph output formats"""
+    JSON = "json"
+    MERMAID = "mermaid"
+    DOT = "dot"
+
+
+@router.get(
+    "/workflow/{workflow_id}/definition",
+    response_model=WorkflowDefinitionGraph,
+    summary="Get workflow definition graph",
+    description="""
+    Generate a static workflow definition graph showing the structure of steps, 
+    activities, timers, and state dependencies as defined in the workflow code.
+    
+    This is similar to Airflow's DAG view - it shows the workflow structure 
+    based on code analysis, not runtime execution.
+    
+    **Features:**
+    - Step sequence and dependencies
+    - Activity calls within each step  
+    - Timer/sleep operations
+    - State read/write dependencies
+    - Workflow metadata
+    
+    **Node Types:**
+    - `step`: Workflow steps (blue boxes)
+    - `activity`: Activity calls (green circles)
+    - `timer`: Sleep/delay operations (yellow diamonds)
+    - `state`: State variables (red hexagons)
+    
+    **Edge Types:**
+    - `sequence`: Step-to-step flow
+    - `calls`: Step calls activity
+    - `reads`: Reads from state
+    - `writes`: Writes to state
+    - `waits`: Step waits on timer
+    """,
+    responses={
+        404: {"model": ErrorResponse, "description": "Workflow not found"},
+        400: {"model": ErrorResponse, "description": "Invalid workflow definition"},
+        500: {"model": ErrorResponse, "description": "Analysis failed"}
+    }
+)
+async def get_workflow_definition_graph(workflow_id: str, db: Database = Depends(get_db)):
+    """Get workflow definition graph as structured data"""
+    try:
+        # Get workflow info from database
+        workflow_info = await db.get_workflow_info(workflow_id)
+        if not workflow_info:
+            raise HTTPException(
+                status_code=404, 
+                detail=f"Workflow with ID '{workflow_id}' not found"
+            )
+        
+        # Get workflow class using module and name from database
+        workflow_class = workflow_registry(workflow_info["module"], workflow_info["name"])
+        
+        # Analyze workflow definition
+        graph = WorkflowAnalyzer.analyze_workflow_definition(workflow_class)
+        
+        return graph
+        
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except (ModuleNotFoundError, AttributeError, TypeError) as e:
+        raise HTTPException(status_code=400, detail=f"Failed to load workflow class: {str(e)}")
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, 
+            detail=f"Failed to analyze workflow: {str(e)}"
+        )
+
+
+@router.get(
+    "/workflow/{workflow_id}/definition/render",
+    response_model=GraphResponse,
+    summary="Render workflow definition graph",
+    description="""
+    Generate a workflow definition graph in various output formats for visualization.
+    
+    **Supported Formats:**
+    - `json`: Structured JSON data (same as /definition endpoint)
+    - `mermaid`: Mermaid diagram syntax for rendering
+    - `dot`: GraphViz DOT format for advanced visualization
+    
+    **Usage Examples:**
+    - Use `mermaid` format to render in web UIs or documentation
+    - Use `dot` format for GraphViz tools (dot, neato, fdp, etc.)
+    - Use `json` format for custom visualization libraries
+    
+    **Mermaid Example:**
+    ```
+    graph TD
+        step_process["Process Order"]
+        activity_payment("process_payment")
+        state_paid{state.payment_confirmed}
+        step_process --> activity_payment
+        step_process --> state_paid
+    ```
+    """,
+    responses={
+        404: {"model": ErrorResponse, "description": "Workflow not found"},
+        400: {"model": ErrorResponse, "description": "Invalid format or workflow"},
+        500: {"model": ErrorResponse, "description": "Rendering failed"}
+    }
+)
+async def render_workflow_definition_graph(
+    workflow_id: str,
+    format: GraphFormatEnum = Query(
+        GraphFormatEnum.MERMAID,
+        description="Output format for the graph"
+    ),
+    db: Database = Depends(get_db)
+):
+    """Render workflow definition graph in specified format"""
+    try:
+        # Get workflow info from database
+        workflow_info = await db.get_workflow_info(workflow_id)
+        if not workflow_info:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Workflow with ID '{workflow_id}' not found"
+            )
+        
+        # Get workflow class using module and name from database
+        workflow_class = workflow_registry(workflow_info["module"], workflow_info["name"])
+        
+        # Analyze workflow definition
+        graph = WorkflowAnalyzer.analyze_workflow_definition(workflow_class)
+        
+        # Generate output based on format
+        if format == GraphFormatEnum.JSON:
+            content = graph.json(indent=2)
+        elif format == GraphFormatEnum.MERMAID:
+            content = generate_mermaid_graph(graph)
+        elif format == GraphFormatEnum.DOT:
+            content = generate_graphviz_dot(graph)
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unsupported format: {format}"
+            )
+        
+        return GraphResponse(
+            format=format.value,
+            content=content,
+            metadata={
+                "workflow_id": workflow_id,
+                "workflow_name": workflow_info["name"],
+                "node_count": len(graph.nodes),
+                "edge_count": len(graph.edges),
+                **graph.metadata
+            }
+        )
+        
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except (ModuleNotFoundError, AttributeError, TypeError) as e:
+        raise HTTPException(status_code=400, detail=f"Failed to load workflow class: {str(e)}")
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to render graph: {str(e)}"
+        )
+
+
+@router.get(
+    "/workflows/",
+    response_model=Dict[str, Any],
+    summary="List workflows for graph generation", 
+    description="""
+    Get a list of all workflows in the database that can be analyzed for graphs.
+    
+    Returns workflow IDs, names, versions, and basic metadata for each workflow.
+    Use the workflow ID with the graph endpoints to generate visualizations.
+    """
+)
+async def list_workflows_for_graphs(db: Database = Depends(get_db)):
+    """List all workflows available for graph generation"""
+    try:
+        # Get all workflows from database
+        workflows_sql = """
+            SELECT id, name, description, version, module, status, created_at, updated_at
+            FROM workflows
+            ORDER BY created_at DESC
+        """
+        workflows = await db.query(workflows_sql)
+        
+        workflow_list = []
+        for workflow in workflows:
+            workflow_list.append({
+                "id": workflow["id"],
+                "name": workflow["name"],
+                "description": workflow["description"] or "",
+                "version": workflow["version"],
+                "module": workflow["module"],
+                "status": workflow["status"],
+                "created_at": workflow["created_at"],
+                "updated_at": workflow["updated_at"]
+            })
+        
+        return {
+            "total_count": len(workflow_list),
+            "workflows": workflow_list
+        }
+        
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to list workflows: {str(e)}"
+        )