edda-framework 0.3.0__tar.gz → 0.4.0__tar.gz

{edda_framework-0.3.0 → edda_framework-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.3.0
+Version: 0.4.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -730,6 +730,32 @@ Each `@durable_tool` automatically generates **three MCP tools**:
 
 This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
 
+### MCP Prompts
+
+Define reusable prompt templates that can access workflow state:
+
+```python
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.types import TextContent
+
+@server.prompt(description="Analyze a workflow execution")
+async def analyze_workflow(instance_id: str) -> UserMessage:
+    """Generate analysis prompt for a specific workflow."""
+    instance = await server.storage.get_instance(instance_id)
+    history = await server.storage.get_history(instance_id)
+
+    text = f"""Analyze this workflow:
+**Status**: {instance['status']}
+**Activities**: {len(history)}
+**Result**: {instance.get('output_data')}
+
+Please provide insights and optimization suggestions."""
+
+    return UserMessage(content=TextContent(type="text", text=text))
+```
+
+AI clients can use these prompts to generate context-aware analysis of your workflows.
+
 **For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
 
 ## Observability Hooks

{edda_framework-0.3.0 → edda_framework-0.4.0}/README.md

@@ -678,6 +678,32 @@ Each `@durable_tool` automatically generates **three MCP tools**:
 
 This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
 
+### MCP Prompts
+
+Define reusable prompt templates that can access workflow state:
+
+```python
+from mcp.server.fastmcp.prompts.base import UserMessage
+from mcp.types import TextContent
+
+@server.prompt(description="Analyze a workflow execution")
+async def analyze_workflow(instance_id: str) -> UserMessage:
+    """Generate analysis prompt for a specific workflow."""
+    instance = await server.storage.get_instance(instance_id)
+    history = await server.storage.get_history(instance_id)
+
+    text = f"""Analyze this workflow:
+**Status**: {instance['status']}
+**Activities**: {len(history)}
+**Result**: {instance.get('output_data')}
+
+Please provide insights and optimization suggestions."""
+
+    return UserMessage(content=TextContent(type="text", text=text))
+```
+
+AI clients can use these prompts to generate context-aware analysis of your workflows.
+
 **For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
 
 ## Observability Hooks

{edda_framework-0.3.0 → edda_framework-0.4.0}/demo_app.py

@@ -492,10 +492,10 @@ async def order_processing_workflow(
             {"item_id": "ITEM-2", "name": "Product B", "price": 49.99, "quantity": 1}
         ],
         "shipping_address": {
-            "street": "123 Main St",
-            "city": "San Francisco",
-            "state": "CA",
-            "zip_code": "94102"
+            "street": "221B Baker Street",
+            "city": "London",
+            "state": "Greater London",
+            "zip_code": "NW1 6XE"
         }
     }
 

{edda_framework-0.3.0 → edda_framework-0.4.0}/docs/core-features/durable-execution/replay.md

@@ -100,9 +100,9 @@ async def arrange_shipping(ctx: WorkflowContext, order_id: str):
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str):
     # Activity IDs are auto-generated for sequential calls
-    inventory = await reserve_inventory(ctx, order_id, activity_id="reserve_inventory:1")
-    payment = await process_payment(ctx, order_id, activity_id="process_payment:1")
-    shipping = await arrange_shipping(ctx, order_id, activity_id="arrange_shipping:1")
+    inventory = await reserve_inventory(ctx, order_id)
+    payment = await process_payment(ctx, order_id)
+    shipping = await arrange_shipping(ctx, order_id)
 
     return {"status": "completed"}
 ```
@@ -497,16 +497,16 @@ async with workflow_lock(storage, instance_id, worker_id):
 ```python
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str):
-    # Activity 1
-    inventory = await reserve_inventory(ctx, order_id, activity_id="reserve_inventory:1")
+    # Activity 1 (auto-generated ID: "reserve_inventory:1")
+    inventory = await reserve_inventory(ctx, order_id)
     # → DB saved: activity_id="reserve_inventory:1", result={"reservation_id": "R123"}
 
-    # Activity 2
-    payment = await process_payment(ctx, order_id, activity_id="process_payment:1")
+    # Activity 2 (auto-generated ID: "process_payment:1")
+    payment = await process_payment(ctx, order_id)
     # → DB saved: activity_id="process_payment:1", result={"transaction_id": "T456"}
 
     # Activity 3: Exception occurs (e.g., network error)
-    shipping = await arrange_shipping(ctx, order_id, activity_id="arrange_shipping:1")
+    shipping = await arrange_shipping(ctx, order_id)
     # → Exception thrown, workflow interrupted
 ```
 

{edda_framework-0.3.0 → edda_framework-0.4.0}/docs/core-features/workflows-activities.md

@@ -147,8 +147,8 @@ async def async_activity(ctx: WorkflowContext, data: str) -> dict:
 async def mixed_workflow(ctx: WorkflowContext, user_id: str) -> dict:
     # Workflows are always async (for deterministic replay)
     # But can call both sync and async activities
-    user = await create_user_record(ctx, user_id, "user@example.com", activity_id="create:1")
-    data = await async_activity(ctx, user_id, activity_id="fetch:1")
+    user = await create_user_record(ctx, user_id, "user@example.com")
+    data = await async_activity(ctx, user_id)
     return {"user": user, "data": data}
 ```
 
@@ -823,8 +823,8 @@ def process_legacy_data(ctx: WorkflowContext, data: str) -> dict:
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str) -> dict:
     # Both sync and async activities work fine
-    user = await create_user_record(ctx, order_id, activity_id="user:1")  # Sync
-    payment = await process_payment(ctx, 99.99, activity_id="pay:1")  # Async
+    user = await create_user_record(ctx, order_id)  # Sync
+    payment = await process_payment(ctx, 99.99)  # Async
     return {"user": user, "payment": payment}
 ```
 

{edda_framework-0.3.0 → edda_framework-0.4.0}/docs/getting-started/first-workflow.md

@@ -272,36 +272,40 @@ async def main():
     # Initialize the app (required before starting workflows)
     await app.initialize()
 
-    # Create order input
-    order = OrderInput(
-        order_id="ORD-12345",
-        customer_email="customer@example.com",
-        items=[
-            OrderItem(product_id="PROD-1", quantity=2, unit_price=29.99),
-            OrderItem(product_id="PROD-2", quantity=1, unit_price=49.99),
-        ],
-        shipping_address=ShippingAddress(
-            street="123 Main St",
-            city="San Francisco",
-            postal_code="94105",
-            country="USA"
+    try:
+        # Create order input
+        order = OrderInput(
+            order_id="ORD-12345",
+            customer_email="customer@example.com",
+            items=[
+                OrderItem(product_id="PROD-1", quantity=2, unit_price=29.99),
+                OrderItem(product_id="PROD-2", quantity=1, unit_price=49.99),
+            ],
+            shipping_address=ShippingAddress(
+                street="1-2-3 Dogenzaka",
+                city="Shibuya",
+                postal_code="150-0001",
+                country="Japan"
+            )
         )
-    )
 
-    # Start workflow
-    print("Starting order processing workflow...")
-    instance_id = await order_processing_workflow.start(input=order)
+        # Start workflow
+        print("Starting order processing workflow...")
+        instance_id = await order_processing_workflow.start(input=order)
+
+        print(f"\n✅ Workflow started: {instance_id}")
 
-    print(f"\n✅ Workflow started: {instance_id}")
+        # Get result
+        instance = await app.storage.get_instance(instance_id)
+        if instance["status"] == "completed":
+            result = instance["output_data"]
+            print(f"📊 Order completed:")
+            print(f"   - Order ID: {result['order_id']}")
+            print(f"   - Total: ${result['total_amount']:.2f}")
+            print(f"   - Tracking: {result['confirmation_number']}")
 
-    # Get result
-    instance = await app.storage.get_instance(instance_id)
-    if instance["status"] == "completed":
-        result = instance["output_data"]
-        print(f"📊 Order completed:")
-        print(f"   - Order ID: {result['order_id']}")
-        print(f"   - Total: ${result['total_amount']:.2f}")
-        print(f"   - Tracking: {result['confirmation_number']}")
+    finally:
+        await app.shutdown()
 
 if __name__ == "__main__":
     asyncio.run(main())
@@ -322,7 +326,7 @@ Starting order processing workflow...
 
 📦 Reserving inventory for ORD-12345: $109.97
 💳 Processing payment for ORD-12345: $109.97
-🚚 Shipping ORD-12345 to San Francisco, USA
+🚚 Shipping ORD-12345 to Shibuya, Japan
 
 ✅ Workflow started: <instance_id>
 📊 Order completed:
@@ -364,7 +368,7 @@ uv run python order_workflow.py
 ```
 📦 Reserving inventory for ORD-12345: $109.97
 💳 Processing payment for ORD-12345: $109.97
-🚚 Shipping ORD-12345 to San Francisco, USA
+🚚 Shipping ORD-12345 to Shibuya, Japan
 💥 Exception: Shipping service unavailable!
 
 ❌ Refunding payment for ORD-12345: $109.97

{edda_framework-0.3.0 → edda_framework-0.4.0}/docs/index.md

@@ -93,21 +93,22 @@ from edda import EddaApp, workflow, activity, WorkflowContext
 
 @activity
 async def process_payment(ctx: WorkflowContext, amount: float):
-    # Durable execution - automatically recorded in history
     print(f"Processing payment: ${amount}")
     return {"status": "paid", "amount": amount}
 
 @workflow
 async def order_workflow(ctx: WorkflowContext, order_id: str, amount: float):
-    # Workflow orchestrates activities with automatic retry on crash
     result = await process_payment(ctx, amount)
     return {"order_id": order_id, **result}
 
-# Simplified example - production code needs:
-# 1. await app.initialize() before starting workflows
-# 2. try-finally with await app.shutdown() for cleanup
-app = EddaApp(service_name="demo-service", db_url="sqlite:///workflow.db")
-instance_id = await order_workflow.start(order_id="ORD-123", amount=99.99)
+async def main():
+    app = EddaApp(service_name="demo-service", db_url="sqlite:///workflow.db")
+    await app.initialize()
+    try:
+        instance_id = await order_workflow.start(order_id="ORD-123", amount=99.99)
+        print(f"Started workflow: {instance_id}")
+    finally:
+        await app.shutdown()
 ```
 
 **What happens on crash?**

{edda_framework-0.3.0 → edda_framework-0.4.0}/edda/integrations/mcp/decorators.py

@@ -4,18 +4,17 @@ from __future__ import annotations
 
 import inspect
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
-from edda.workflow import workflow
+from edda.workflow import Workflow, workflow
 
 if TYPE_CHECKING:
     from edda.integrations.mcp.server import EddaMCPServer
-    from edda.workflow import Workflow
 
 
 def create_durable_tool(
     server: EddaMCPServer,
-    func: Callable,
+    func: Callable[..., Any],
     *,
     description: str = "",
 ) -> Workflow:
@@ -38,7 +37,7 @@ def create_durable_tool(
         Workflow instance
     """
     # 1. Create Edda workflow
-    workflow_instance: Workflow = workflow(func, event_handler=False)
+    workflow_instance = cast(Workflow, workflow(func, event_handler=False))
     workflow_name = func.__name__
 
     # Register in server's workflow registry
@@ -56,7 +55,7 @@ def create_durable_tool(
     ]
 
     # Create the tool function
-    async def start_tool(**kwargs: Any) -> dict:
+    async def start_tool(**kwargs: Any) -> dict[str, Any]:
         """
         Start workflow and return instance_id.
 
@@ -94,11 +93,21 @@ def create_durable_tool(
     status_tool_name = f"{workflow_name}_status"
     status_tool_description = f"Check status of {workflow_name} workflow"
 
-    @server._mcp.tool(name=status_tool_name, description=status_tool_description)
-    async def status_tool(instance_id: str) -> dict:
+    @server._mcp.tool(name=status_tool_name, description=status_tool_description)  # type: ignore[misc]
+    async def status_tool(instance_id: str) -> dict[str, Any]:
         """Check workflow status."""
         try:
-            instance = await server._edda_app.storage.get_instance(instance_id)
+            instance = await server.storage.get_instance(instance_id)
+            if instance is None:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"Workflow instance not found: {instance_id}",
+                        }
+                    ],
+                    "isError": True,
+                }
 
             status = instance["status"]
             current_activity_id = instance.get("current_activity_id", "N/A")
@@ -128,11 +137,21 @@ def create_durable_tool(
     result_tool_name = f"{workflow_name}_result"
     result_tool_description = f"Get result of {workflow_name} workflow (if completed)"
 
-    @server._mcp.tool(name=result_tool_name, description=result_tool_description)
-    async def result_tool(instance_id: str) -> dict:
+    @server._mcp.tool(name=result_tool_name, description=result_tool_description)  # type: ignore[misc]
+    async def result_tool(instance_id: str) -> dict[str, Any]:
         """Get workflow result (if completed)."""
         try:
-            instance = await server._edda_app.storage.get_instance(instance_id)
+            instance = await server.storage.get_instance(instance_id)
+            if instance is None:
+                return {
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": f"Workflow instance not found: {instance_id}",
+                        }
+                    ],
+                    "isError": True,
+                }
 
             status = instance["status"]
 

{edda_framework-0.3.0 → edda_framework-0.4.0}/edda/integrations/mcp/server.py

@@ -3,13 +3,16 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import Any
+from typing import TYPE_CHECKING, Any, cast
 
 from edda.app import EddaApp
 from edda.workflow import Workflow
 
+if TYPE_CHECKING:
+    from edda.storage.protocol import StorageProtocol
+
 try:
-    from mcp.server.fastmcp import FastMCP
+    from mcp.server.fastmcp import FastMCP  # type: ignore[import-not-found]
 except ImportError as e:
     raise ImportError(
         "MCP Python SDK is required for MCP integration. "
@@ -45,7 +48,13 @@ class EddaMCPServer:
 
         # Deploy with uvicorn (HTTP transport)
         if __name__ == "__main__":
+            import asyncio
             import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            asyncio.run(startup())
             uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
 
         # Or deploy with stdio (for MCP clients, e.g., Claude Desktop)
@@ -89,7 +98,7 @@ class EddaMCPServer:
             service_name=name,
             db_url=db_url,
             outbox_enabled=outbox_enabled,
-            broker_url=broker_url,
+            broker_url=broker_url or "",
         )
         self._mcp = FastMCP(name, json_response=True, stateless_http=True)
         self._token_verifier = token_verifier
@@ -97,12 +106,28 @@ class EddaMCPServer:
         # Registry of durable tools (workflow_name -> Workflow instance)
         self._workflows: dict[str, Workflow] = {}
 
+    @property
+    def storage(self) -> StorageProtocol:
+        """
+        Access workflow storage for querying instances and history.
+
+        Returns:
+            StorageProtocol: Storage backend for workflow state
+
+        Example:
+            ```python
+            instance = await server.storage.get_instance(instance_id)
+            history = await server.storage.get_history(instance_id)
+            ```
+        """
+        return self._edda_app.storage
+
     def durable_tool(
         self,
-        func: Callable | None = None,
+        func: Callable[..., Any] | None = None,
         *,
         description: str = "",
-    ) -> Callable:
+    ) -> Callable[..., Any]:
         """
         Decorator to define a durable workflow tool.
 
@@ -128,14 +153,67 @@ class EddaMCPServer:
         """
         from edda.integrations.mcp.decorators import create_durable_tool
 
-        def decorator(f: Callable) -> Workflow:
+        def decorator(f: Callable[..., Any]) -> Workflow:
             return create_durable_tool(self, f, description=description)
 
         if func is None:
             return decorator
         return decorator(func)
 
-    def asgi_app(self) -> Callable:
+    def prompt(
+        self,
+        func: Callable[..., Any] | None = None,
+        *,
+        description: str = "",
+    ) -> Callable[..., Any]:
+        """
+                Decorator to define a prompt template.
+
+                Prompts can access workflow state to generate dynamic, context-aware
+                prompts for AI clients (Claude Desktop, etc.).
+
+                Args:
+                    func: Prompt function (async or sync)
+                    description: Prompt description for MCP clients
+
+                Returns:
+                    Decorated function
+
+                Example:
+                    ```python
+                    from fastmcp.prompts.prompt import PromptMessage, TextContent
+
+                    @server.prompt(description="Analyze workflow results")
+                    async def analyze_workflow(instance_id: str) -> PromptMessage:
+                        '''Generate a prompt to analyze a specific workflow execution.'''
+                        instance = await server.storage.get_instance(instance_id)
+                        history = await server.storage.get_history(instance_id)
+
+                        text = f'''Analyze this workflow:
+
+        Instance ID: {instance_id}
+        Status: {instance['status']}
+        Activities: {len(history)}
+
+        Please identify any issues or optimization opportunities.'''
+
+                        return PromptMessage(
+                            role="user",
+                            content=TextContent(type="text", text=text)
+                        )
+                    ```
+        """
+
+        def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
+            # Use FastMCP's native prompt decorator
+            prompt_desc = description or f.__doc__ or f"Prompt: {f.__name__}"
+            return cast(Callable[..., Any], self._mcp.prompt(description=prompt_desc)(f))
+
+        if func is None:
+            return decorator
+        return decorator(func)
+
+    def asgi_app(self) -> Callable[..., Any]:
         """
         Create ASGI application with MCP + CloudEvents support.
 
@@ -150,8 +228,8 @@ class EddaMCPServer:
         Returns:
             ASGI callable (Starlette app)
         """
-        from starlette.requests import Request
-        from starlette.responses import Response
+        from starlette.requests import Request  # type: ignore[import-not-found]
+        from starlette.responses import Response  # type: ignore[import-not-found]
 
         # Get MCP's Starlette app (Issue #1367 workaround: use directly)
         app = self._mcp.streamable_http_app()
@@ -169,9 +247,9 @@ class EddaMCPServer:
             scope["path"] = f"/cancel/{instance_id}"
 
             # Capture response
-            response_data = {"status": 200, "headers": [], "body": b""}
+            response_data: dict[str, Any] = {"status": 200, "headers": [], "body": b""}
 
-            async def send(message: dict) -> None:
+            async def send(message: dict[str, Any]) -> None:
                 if message["type"] == "http.response.start":
                     response_data["status"] = message["status"]
                     response_data["headers"] = message.get("headers", [])
@@ -185,7 +263,7 @@ class EddaMCPServer:
             return Response(
                 content=response_data["body"],
                 status_code=response_data["status"],
-                headers=dict(response_data["headers"]),
+                headers=cast(dict[str, str], dict(response_data["headers"])),
             )
 
         # Add cancel route
@@ -193,14 +271,18 @@ class EddaMCPServer:
 
         # Add authentication middleware if token_verifier provided (AFTER adding routes)
         if self._token_verifier is not None:
-            from starlette.middleware.base import BaseHTTPMiddleware
+            from starlette.middleware.base import (  # type: ignore[import-not-found]
+                BaseHTTPMiddleware,
+            )
 
-            class AuthMiddleware(BaseHTTPMiddleware):
-                def __init__(self, app: Any, token_verifier: Callable):
+            class AuthMiddleware(BaseHTTPMiddleware):  # type: ignore[misc]
+                def __init__(self, app: Any, token_verifier: Callable[[str], bool]):
                     super().__init__(app)
                     self.token_verifier = token_verifier
 
-                async def dispatch(self, request: Request, call_next: Callable):
+                async def dispatch(
+                    self, request: Request, call_next: Callable[..., Any]
+                ) -> Response:
                     auth_header = request.headers.get("authorization", "")
                     if auth_header.startswith("Bearer "):
                         token = auth_header[7:]
@@ -211,17 +293,15 @@ class EddaMCPServer:
             # Wrap app with auth middleware
             app = AuthMiddleware(app, self._token_verifier)
 
-        return app
+        return cast(Callable[..., Any], app)
 
     async def initialize(self) -> None:
         """
         Initialize the EddaApp (setup replay engine, storage, etc.).
 
-        This method must be called before running the server in stdio mode.
-        For HTTP mode (asgi_app()), initialization happens automatically
-        when the ASGI app is deployed.
+        This method must be called before running the server in either stdio or HTTP mode.
 
-        Example:
+        Example (stdio mode):
             ```python
             async def main():
                 await server.initialize()
@@ -231,9 +311,85 @@ class EddaMCPServer:
                 import asyncio
                 asyncio.run(main())
             ```
+
+        Example (HTTP mode):
+            ```python
+            import asyncio
+            import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            asyncio.run(startup())
+            uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+            ```
         """
         await self._edda_app.initialize()
 
+    async def shutdown(self) -> None:
+        """
+        Shutdown the server and cleanup resources.
+
+        Stops background tasks (auto-resume, timer checks, event timeouts),
+        closes storage connections, and performs graceful shutdown.
+
+        This method should be called when the server is shutting down.
+
+        Example (stdio mode):
+            ```python
+            import signal
+            import asyncio
+
+            async def main():
+                server = EddaMCPServer(...)
+                await server.initialize()
+
+                # Setup signal handlers for graceful shutdown
+                loop = asyncio.get_running_loop()
+                shutdown_event = asyncio.Event()
+
+                def signal_handler():
+                    shutdown_event.set()
+
+                for sig in (signal.SIGTERM, signal.SIGINT):
+                    loop.add_signal_handler(sig, signal_handler)
+
+                # Run server
+                try:
+                    await server.run_stdio()
+                finally:
+                    await server.shutdown()
+
+            if __name__ == "__main__":
+                asyncio.run(main())
+            ```
+
+        Example (HTTP mode with uvicorn):
+            ```python
+            import asyncio
+            import uvicorn
+
+            async def startup():
+                await server.initialize()
+
+            async def shutdown_handler():
+                await server.shutdown()
+
+            # Use uvicorn lifecycle events
+            config = uvicorn.Config(
+                server.asgi_app(),
+                host="0.0.0.0",
+                port=8000,
+            )
+            server_instance = uvicorn.Server(config)
+
+            # Uvicorn handles SIGTERM/SIGINT automatically
+            await server_instance.serve()
+            await shutdown_handler()
+            ```
+        """
+        await self._edda_app.shutdown()
+
     async def run_stdio(self) -> None:
         """
         Run MCP server with stdio transport (for MCP clients, e.g., Claude Desktop).