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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.1.0
+Version: 0.3.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -20,7 +20,9 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: System :: Distributed Computing
 Requires-Python: >=3.11
+Requires-Dist: a2wsgi>=1.10.0
 Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: anyio>=4.0.0
 Requires-Dist: cloudevents>=1.12.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic>=2.0.0
@@ -36,6 +38,8 @@ Requires-Dist: ruff>=0.14.2; 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: mcp
+Requires-Dist: mcp>=1.22.0; extra == 'mcp'
 Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
 Provides-Extra: postgresql
@@ -75,6 +79,8 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
+- 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
+- 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
 
@@ -638,6 +644,94 @@ api.mount("/workflows", edda_app)
 
 This works with any ASGI framework (Starlette, FastAPI, Quart, etc.)
 
+### WSGI Integration
+
+For WSGI environments (gunicorn, uWSGI, Flask, Django), use the WSGI adapter:
+
+```python
+from edda import EddaApp
+from edda.wsgi import create_wsgi_app
+
+# Create Edda app
+edda_app = EddaApp(db_url="sqlite:///workflow.db")
+
+# Convert to WSGI
+wsgi_application = create_wsgi_app(edda_app)
+```
+
+**Running with WSGI servers:**
+
+```bash
+# With Gunicorn
+gunicorn demo_app:wsgi_application --workers 4
+
+# With uWSGI
+uwsgi --http :8000 --wsgi-file demo_app.py --callable wsgi_application
+```
+
+**Sync Activities**: For WSGI environments or legacy codebases, you can write synchronous activities:
+
+```python
+from edda import activity, WorkflowContext
+
+@activity
+def process_payment(ctx: WorkflowContext, amount: float) -> dict:
+    # Sync function - automatically executed in thread pool
+    # No async/await needed!
+    return {"status": "paid", "amount": amount}
+
+@workflow
+async def payment_workflow(ctx: WorkflowContext, order_id: str) -> dict:
+    # Workflows still use async (for deterministic replay)
+    result = await process_payment(ctx, 99.99, activity_id="pay:1")
+    return result
+```
+
+**Performance note**: ASGI servers (uvicorn, hypercorn) are recommended for better performance with Edda's async architecture. WSGI support is provided for compatibility with existing infrastructure and users who prefer synchronous programming.
+
+## MCP Integration
+
+Edda integrates with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing AI assistants like Claude to interact with your durable workflows as long-running tools.
+
+### Quick Example
+
+```python
+from edda.integrations.mcp import EddaMCPServer
+from edda import WorkflowContext, activity
+
+# Create MCP server
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+)
+
+@activity
+async def process_payment(ctx: WorkflowContext, amount: float):
+    return {"status": "paid", "amount": amount}
+
+@server.durable_tool(description="Process customer order")
+async def process_order(ctx: WorkflowContext, order_id: str):
+    await process_payment(ctx, 99.99)
+    return {"status": "completed", "order_id": order_id}
+
+# Deploy with uvicorn
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+```
+
+### Auto-Generated Tools
+
+Each `@durable_tool` automatically generates **three MCP tools**:
+
+1. **Main tool** (`process_order`): Starts the workflow, returns instance ID
+2. **Status tool** (`process_order_status`): Checks workflow progress
+3. **Result tool** (`process_order_result`): Gets final result when completed
+
+This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
+
+**For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
+
 ## Observability Hooks
 
 Extend Edda with custom observability without coupling to specific tools:

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

@@ -27,6 +27,8 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
+- 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
+- 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
 
@@ -590,6 +592,94 @@ api.mount("/workflows", edda_app)
 
 This works with any ASGI framework (Starlette, FastAPI, Quart, etc.)
 
+### WSGI Integration
+
+For WSGI environments (gunicorn, uWSGI, Flask, Django), use the WSGI adapter:
+
+```python
+from edda import EddaApp
+from edda.wsgi import create_wsgi_app
+
+# Create Edda app
+edda_app = EddaApp(db_url="sqlite:///workflow.db")
+
+# Convert to WSGI
+wsgi_application = create_wsgi_app(edda_app)
+```
+
+**Running with WSGI servers:**
+
+```bash
+# With Gunicorn
+gunicorn demo_app:wsgi_application --workers 4
+
+# With uWSGI
+uwsgi --http :8000 --wsgi-file demo_app.py --callable wsgi_application
+```
+
+**Sync Activities**: For WSGI environments or legacy codebases, you can write synchronous activities:
+
+```python
+from edda import activity, WorkflowContext
+
+@activity
+def process_payment(ctx: WorkflowContext, amount: float) -> dict:
+    # Sync function - automatically executed in thread pool
+    # No async/await needed!
+    return {"status": "paid", "amount": amount}
+
+@workflow
+async def payment_workflow(ctx: WorkflowContext, order_id: str) -> dict:
+    # Workflows still use async (for deterministic replay)
+    result = await process_payment(ctx, 99.99, activity_id="pay:1")
+    return result
+```
+
+**Performance note**: ASGI servers (uvicorn, hypercorn) are recommended for better performance with Edda's async architecture. WSGI support is provided for compatibility with existing infrastructure and users who prefer synchronous programming.
+
+## MCP Integration
+
+Edda integrates with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing AI assistants like Claude to interact with your durable workflows as long-running tools.
+
+### Quick Example
+
+```python
+from edda.integrations.mcp import EddaMCPServer
+from edda import WorkflowContext, activity
+
+# Create MCP server
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+)
+
+@activity
+async def process_payment(ctx: WorkflowContext, amount: float):
+    return {"status": "paid", "amount": amount}
+
+@server.durable_tool(description="Process customer order")
+async def process_order(ctx: WorkflowContext, order_id: str):
+    await process_payment(ctx, 99.99)
+    return {"status": "completed", "order_id": order_id}
+
+# Deploy with uvicorn
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+```
+
+### Auto-Generated Tools
+
+Each `@durable_tool` automatically generates **three MCP tools**:
+
+1. **Main tool** (`process_order`): Starts the workflow, returns instance ID
+2. **Status tool** (`process_order_status`): Checks workflow progress
+3. **Result tool** (`process_order_result`): Gets final result when completed
+
+This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
+
+**For detailed documentation**, see [MCP Integration Guide](docs/integrations/mcp.md).
+
 ## Observability Hooks
 
 Extend Edda with custom observability without coupling to specific tools:

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

@@ -1817,3 +1817,9 @@ async def scheduled_order_shipment_workflow(
 # Export as ASGI application
 # No need to manually register event handlers!
 application = app
+
+# Export as WSGI application (for gunicorn, uWSGI, etc.)
+# Usage: gunicorn demo_app:wsgi_application --workers 4
+from edda.wsgi import create_wsgi_app
+
+wsgi_application = create_wsgi_app(app)

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

@@ -121,6 +121,46 @@ async def create_order_with_db(ctx: WorkflowContext, order_id: str):
     return {"order_id": order_id}
 ```
 
+### Sync Activities (WSGI Compatibility)
+
+For WSGI environments (gunicorn, uWSGI) or legacy codebases, Edda supports synchronous activities:
+
+```python
+from edda import activity, WorkflowContext
+
+@activity
+def create_user_record(ctx: WorkflowContext, user_id: str, email: str) -> dict:
+    """Sync activity - executed in thread pool"""
+    # Traditional sync code - no async/await needed!
+    user = User(user_id=user_id, email=email)
+    db.session.add(user)
+    db.session.commit()
+    return {"user_id": user.id}
+
+@activity
+async def async_activity(ctx: WorkflowContext, data: str) -> dict:
+    """Async activity - recommended for I/O operations"""
+    result = await httpx.get(f"https://api.example.com/{data}")
+    return result.json()
+
+@workflow
+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")
+    return {"user": user, "data": data}
+```
+
+**When to use sync activities:**
+
+- ✅ Existing sync codebases (Flask, Django)
+- ✅ WSGI deployments (gunicorn, uWSGI)
+- ✅ Libraries without async support
+- ✅ Simple CPU-bound operations
+
+**Performance note:** Async activities are recommended for I/O-bound operations (database queries, HTTP requests, file I/O) for better performance. Sync activities are executed in a thread pool to avoid blocking the event loop.
+
 ## Retry Policies
 
 Activities automatically retry on failure with exponential backoff. This provides resilience against transient failures like network timeouts or temporary service unavailability.
@@ -755,26 +795,41 @@ async def order_workflow(ctx: WorkflowContext, order_id: str, amount: float):
     pass
 ```
 
-### 4. Don't Mix Async/Sync
+### 4. Choose Async or Sync Appropriately
 
-❌ **Bad:**
+✅ **Preferred: Async activities** (better performance for I/O)
 
 ```python
 @activity
-def sync_activity(ctx: WorkflowContext, param: str):  # ❌ Not async!
-    # This won't work!
-    pass
+async def fetch_user_data(ctx: WorkflowContext, user_id: str) -> dict:
+    # Async I/O operations (recommended)
+    result = await httpx.get(f"https://api.example.com/users/{user_id}")
+    return result.json()
 ```
 
-✅ **Good:**
+✅ **Valid: Sync activities** (WSGI compatibility, legacy code)
 
 ```python
 @activity
-async def async_activity(ctx: WorkflowContext, param: str):  # ✅ Async
-    # Correct!
-    pass
+def process_legacy_data(ctx: WorkflowContext, data: str) -> dict:
+    # Sync operations (executed in thread pool)
+    result = legacy_library.process(data)  # No async support
+    return {"processed": result}
 ```
 
+✅ **Good: Mix sync and async in same workflow**
+
+```python
+@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
+    return {"user": user, "payment": payment}
+```
+
+**Performance tip**: Prefer async activities for I/O-bound operations (database queries, HTTP requests, file I/O). Use sync activities when integrating with legacy code or libraries without async support.
+
 ## Next Steps
 
 - **[Durable Execution](durable-execution/replay.md)**: Learn how Edda ensures workflows never lose progress

edda_framework-0.3.0/docs/integrations/mcp.md

@@ -0,0 +1,230 @@
+# MCP (Model Context Protocol) Integration
+
+Edda provides seamless integration with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing AI assistants like Claude to interact with your durable workflows as long-running tools.
+
+## Overview
+
+MCP is a standardized protocol for AI tool integration. Edda's MCP integration automatically converts your durable workflows into MCP-compliant tools that:
+
+- **Start workflows** and return instance IDs immediately
+- **Check workflow status** to monitor progress
+- **Retrieve results** when workflows complete
+
+This enables AI assistants to work with long-running processes that may take minutes, hours, or even days to complete.
+
+## Installation
+
+Install Edda with MCP support:
+
+```bash
+pip install edda-framework[mcp]
+
+# Or using uv
+uv add edda-framework --extra mcp
+```
+
+## Quick Start
+
+### 1. Create an MCP Server
+
+```python
+from edda.integrations.mcp import EddaMCPServer
+from edda import WorkflowContext, activity
+
+# Create MCP server
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+)
+
+@activity
+async def reserve_inventory(ctx: WorkflowContext, items: list[str]):
+    # Your business logic here
+    return {"reserved": True}
+
+@activity
+async def process_payment(ctx: WorkflowContext, amount: float):
+    # Payment processing logic
+    return {"transaction_id": "txn_123"}
+
+@server.durable_tool(description="Process customer order workflow")
+async def process_order(ctx: WorkflowContext, order_id: str, items: list[str]):
+    """
+    Long-running order processing workflow.
+
+    This workflow reserves inventory, processes payment, and ships the order.
+    """
+    # Reserve inventory
+    await reserve_inventory(ctx, items)
+
+    # Process payment
+    await process_payment(ctx, 99.99)
+
+    return {"status": "completed", "order_id": order_id}
+```
+
+### 2. Deploy the Server
+
+```python
+# Deploy with uvicorn (production)
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(server.asgi_app(), host="0.0.0.0", port=8000)
+```
+
+```bash
+# Run the server
+uvicorn your_app:server.asgi_app --host 0.0.0.0 --port 8000
+```
+
+### 3. Use from MCP Clients (e.g., Claude Desktop)
+
+Add to your MCP client configuration (e.g., Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "order-service": {
+      "command": "uvicorn",
+      "args": ["your_app:server.asgi_app", "--host", "127.0.0.1", "--port", "8000"],
+      "env": {
+        "DATABASE_URL": "postgresql://user:pass@localhost/orders"
+      }
+    }
+  }
+}
+```
+
+## Auto-Generated Tools
+
+Each `@durable_tool` automatically generates **three MCP tools**:
+
+### 1. Main Tool: Start Workflow
+
+```
+Tool Name: process_order
+Description: Process customer order workflow
+
+Input: {"order_id": "ORD-123", "items": ["item1", "item2"]}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow 'process_order' started successfully.\nInstance ID: abc123...\n\nUse 'process_order_status' tool to check progress."
+  }],
+  "isError": false
+}
+```
+
+### 2. Status Tool: Check Progress
+
+```
+Tool Name: process_order_status
+Description: Check status of process_order workflow
+
+Input: {"instance_id": "abc123..."}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow Status: running\nCurrent Activity: payment:1\nInstance ID: abc123..."
+  }],
+  "isError": false
+}
+```
+
+### 3. Result Tool: Get Final Result
+
+```
+Tool Name: process_order_result
+Description: Get result of process_order workflow (if completed)
+
+Input: {"instance_id": "abc123..."}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow Result:\n{'status': 'completed', 'order_id': 'ORD-123'}"
+  }],
+  "isError": false
+}
+```
+
+## Advanced Configuration
+
+### Authentication
+
+Protect your MCP server with token-based authentication:
+
+```python
+def verify_token(token: str) -> bool:
+    # Your token verification logic
+    return token == "secret-token-123"
+
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+    token_verifier=verify_token,
+)
+```
+
+Clients must include the token in the Authorization header:
+
+```http
+Authorization: Bearer secret-token-123
+```
+
+### Transactional Outbox Pattern
+
+Enable event-driven architecture with outbox pattern:
+
+```python
+server = EddaMCPServer(
+    name="Order Service",
+    db_url="postgresql://user:pass@localhost/orders",
+    outbox_enabled=True,
+    broker_url="nats://localhost:4222",
+)
+```
+
+## MCP Protocol Compliance
+
+Edda's MCP integration follows the [MCP Tools specification](https://modelcontextprotocol.io/docs/concepts/tools):
+
+- **JSON-RPC 2.0**: All communication uses JSON-RPC 2.0 protocol
+- **Content Arrays**: Responses include `content` array with text/image/resource items
+- **Error Handling**: Errors are reported with `isError: true` flag
+- **Stateless HTTP**: Uses MCP's streamable HTTP transport for production deployments
+
+## Architecture
+
+```
+┌─────────────────┐
+│    MCP Client   │
+└────────┬────────┘
+         │ JSON-RPC 2.0
+         │ (HTTP Transport)
+         ▼
+┌─────────────────┐
+│  EddaMCPServer  │
+│   ┌─────────┐   │
+│   │ FastMCP │   │  ← Official MCP SDK
+│   └─────────┘   │
+│   ┌─────────┐   │
+│   │ EddaApp │   │  ← Durable Execution
+│   └─────────┘   │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│    Database     │
+└─────────────────┘
+```
+
+
+## Related Documentation
+
+- [Edda Workflows and Activities](../core-features/workflows-activities.md)
+- [Transactional Outbox Pattern](../core-features/transactional-outbox.md)
+- [MCP Protocol Specification](https://modelcontextprotocol.io/)
+
+## Examples
+
+See the [examples/mcp/](../../examples/mcp/) directory for complete working examples.

{edda_framework-0.1.0 → edda_framework-0.3.0}/edda/__init__.py

@@ -30,6 +30,7 @@ from edda.hooks import HooksBase, WorkflowHooks
 from edda.outbox import OutboxRelayer, send_event_transactional
 from edda.retry import RetryPolicy
 from edda.workflow import workflow
+from edda.wsgi import create_wsgi_app
 
 __version__ = "0.1.0"
 
@@ -53,4 +54,5 @@ __all__ = [
     "RetryPolicy",
     "RetryExhaustedError",
     "TerminalError",
+    "create_wsgi_app",
 ]