edda-framework 0.9.1__tar.gz → 0.11.0__tar.gz

{edda_framework-0.9.1 → edda_framework-0.11.0}/Justfile

@@ -11,7 +11,7 @@ install:
 
 # Install all dependencies including database drivers
 install-all:
-    uv sync --extra dev --extra postgresql --extra mysql
+    uv sync --extra dev --extra postgresql --extra mysql --extra postgres-notify
 
 # Install viewer dependencies
 install-viewer:
@@ -71,15 +71,32 @@ demo:
 # Run demo application with PostgreSQL (requires local PostgreSQL)
 # Usage: just demo-postgresql
 # Requires: EDDA_POSTGRES_PASSWORD environment variable
+# Uses LISTEN/NOTIFY for instant notifications (auto-detected)
 demo-postgresql:
+    @echo "Stopping existing demo app on port 8001..."
+    @lsof -ti :8001 | xargs kill -15 2>/dev/null || true
+    @sleep 1
+    @lsof -ti :8001 | xargs kill -9 2>/dev/null || true
+    @echo "Ensuring server and PostgreSQL dependencies are installed..."
+    @uv sync --extra server --extra postgresql --extra postgres-notify --quiet
+    @echo "Starting demo app with PostgreSQL (NOTIFY enabled)..."
+    EDDA_DB_URL="postgresql+asyncpg://postgres:{{env_var('EDDA_POSTGRES_PASSWORD')}}@localhost:5432/edda" \
+    uv run tsuno demo_app:application --bind 127.0.0.1:8001
+
+# Run demo application with PostgreSQL but WITHOUT NOTIFY (polling only)
+# Usage: just demo-postgresql-polling
+# Requires: EDDA_POSTGRES_PASSWORD environment variable
+# Uses polling-only mode (no LISTEN/NOTIFY) for comparison testing
+demo-postgresql-polling:
     @echo "Stopping existing demo app on port 8001..."
     @lsof -ti :8001 | xargs kill -15 2>/dev/null || true
     @sleep 1
     @lsof -ti :8001 | xargs kill -9 2>/dev/null || true
     @echo "Ensuring server and PostgreSQL dependencies are installed..."
     @uv sync --extra server --extra postgresql --quiet
-    @echo "Starting demo app with PostgreSQL..."
+    @echo "Starting demo app with PostgreSQL (polling only, NOTIFY disabled)..."
     EDDA_DB_URL="postgresql+asyncpg://postgres:{{env_var('EDDA_POSTGRES_PASSWORD')}}@localhost:5432/edda" \
+    EDDA_USE_NOTIFY=false \
     uv run tsuno demo_app:application --bind 127.0.0.1:8001
 
 # Run viewer with demo_app using PostgreSQL (requires local PostgreSQL)

{edda_framework-0.9.1 → edda_framework-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.9.1
+Version: 0.11.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -28,6 +28,8 @@ Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: sqlalchemy[asyncio]>=2.0.0
 Requires-Dist: uvloop>=0.22.1
+Provides-Extra: cpu-monitor
+Requires-Dist: psutil>=5.9.0; extra == 'cpu-monitor'
 Provides-Extra: dev
 Requires-Dist: black>=25.9.0; extra == 'dev'
 Requires-Dist: mcp>=1.22.0; extra == 'dev'
@@ -42,12 +44,17 @@ 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: mirascope
+Requires-Dist: mirascope[anthropic,google,openai]>=2.0.0a0; extra == 'mirascope'
+Requires-Dist: pydantic-settings>=2.0.0; extra == 'mirascope'
 Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
 Provides-Extra: opentelemetry
 Requires-Dist: opentelemetry-api>=1.20.0; extra == 'opentelemetry'
 Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'opentelemetry'
 Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'opentelemetry'
+Provides-Extra: postgres-notify
+Requires-Dist: asyncpg>=0.30.0; extra == 'postgres-notify'
 Provides-Extra: postgresql
 Requires-Dist: asyncpg>=0.30.0; extra == 'postgresql'
 Provides-Extra: server
@@ -87,7 +94,9 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - ☁️ **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
 - 📬 **Channel-based Messaging**: Actor-model style communication with competing (job queue) and broadcast (fan-out) modes
+- ⚡ **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
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
@@ -221,6 +230,9 @@ uv add edda-framework --extra mysql
 # With Viewer UI
 uv add edda-framework --extra viewer
 
+# With PostgreSQL instant notifications (LISTEN/NOTIFY)
+uv add edda-framework --extra postgres-notify
+
 # All extras (PostgreSQL, MySQL, Viewer UI)
 uv add edda-framework --extra postgresql --extra mysql --extra viewer
 ```
@@ -272,6 +284,8 @@ pip install "git+https://github.com/i2y/edda.git[postgresql,viewer]"
 
 **Important**: For multi-process or multi-pod deployments (K8s, Docker Compose with multiple replicas, etc.), you **must** use PostgreSQL or MySQL. SQLite supports multiple async workers within a single process, but its table-level locking makes it unsuitable for multi-process/multi-pod scenarios.
 
+> **Tip**: For PostgreSQL, install the `postgres-notify` extra for near-instant event delivery using LISTEN/NOTIFY instead of polling.
+
 ### Development Installation
 
 If you want to contribute to Edda or modify the framework itself:
@@ -492,6 +506,8 @@ app = EddaApp(
     # Connection pool settings (optional)
     pool_size=5,        # Concurrent connections
     max_overflow=10,    # Additional burst capacity
+    # Batch processing (optional)
+    max_workflows_per_batch=10,  # Or "auto" / "auto:cpu" for dynamic scaling
 )
 ```
 

{edda_framework-0.9.1 → edda_framework-0.11.0}/README.md

@@ -29,7 +29,9 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - ☁️ **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
 - 📬 **Channel-based Messaging**: Actor-model style communication with competing (job queue) and broadcast (fan-out) modes
+- ⚡ **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
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
@@ -163,6 +165,9 @@ uv add edda-framework --extra mysql
 # With Viewer UI
 uv add edda-framework --extra viewer
 
+# With PostgreSQL instant notifications (LISTEN/NOTIFY)
+uv add edda-framework --extra postgres-notify
+
 # All extras (PostgreSQL, MySQL, Viewer UI)
 uv add edda-framework --extra postgresql --extra mysql --extra viewer
 ```
@@ -214,6 +219,8 @@ pip install "git+https://github.com/i2y/edda.git[postgresql,viewer]"
 
 **Important**: For multi-process or multi-pod deployments (K8s, Docker Compose with multiple replicas, etc.), you **must** use PostgreSQL or MySQL. SQLite supports multiple async workers within a single process, but its table-level locking makes it unsuitable for multi-process/multi-pod scenarios.
 
+> **Tip**: For PostgreSQL, install the `postgres-notify` extra for near-instant event delivery using LISTEN/NOTIFY instead of polling.
+
 ### Development Installation
 
 If you want to contribute to Edda or modify the framework itself:
@@ -434,6 +441,8 @@ app = EddaApp(
     # Connection pool settings (optional)
     pool_size=5,        # Concurrent connections
     max_overflow=10,    # Additional burst capacity
+    # Batch processing (optional)
+    max_workflows_per_batch=10,  # Or "auto" / "auto:cpu" for dynamic scaling
 )
 ```
 

{edda_framework-0.9.1 → edda_framework-0.11.0}/demo_app.py

@@ -1,6 +1,7 @@
 """Demo Edda ASGI application for tsuno."""
 
 import asyncio
+import logging
 import os
 import sys
 from datetime import datetime
@@ -8,9 +9,17 @@ from enum import Enum
 from typing import Any, cast
 
 import uvloop
-from pydantic import BaseModel, Field, field_validator
 
-from edda import (
+# Configure logging to see Edda startup messages (must be before edda import)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+from pydantic import BaseModel, Field, field_validator  # noqa: E402
+
+from edda import (  # noqa: E402
     EddaApp,
     RetryPolicy,
     WorkflowContext,
@@ -24,7 +33,7 @@ from edda import (
     wait_until,
     workflow,
 )
-from edda.wsgi import create_wsgi_app
+from edda.wsgi import create_wsgi_app  # noqa: E402
 
 # Python 3.12+ uses asyncio.set_event_loop_policy() instead of uvloop.install()
 if sys.version_info >= (3, 12):
@@ -408,9 +417,18 @@ class ScheduledShipmentResult(BaseModel):
 
 # Create Edda application
 # Use environment variable EDDA_DB_URL if available, otherwise default to sqlite:///demo.db
+# Use EDDA_USE_NOTIFY to control LISTEN/NOTIFY (true/false/auto, default: auto)
+_use_notify_env = os.getenv("EDDA_USE_NOTIFY", "auto").lower()
+_use_listen_notify: bool | None = None  # Auto-detect
+if _use_notify_env == "true":
+    _use_listen_notify = True
+elif _use_notify_env == "false":
+    _use_listen_notify = False
+
 app = EddaApp(
     service_name="demo-service",
     db_url=os.getenv("EDDA_DB_URL", "sqlite:///demo.db"),
+    use_listen_notify=_use_listen_notify,
 )
 
 
@@ -2115,7 +2133,7 @@ async def job_publisher_workflow(
     """
     print(f"\n[PUBLISHER] Publishing job: {input.task}")
     await publish(ctx, "jobs", {"task": input.task})
-    print(f"[PUBLISHER] Job published to 'jobs' channel")
+    print("[PUBLISHER] Job published to 'jobs' channel")
     return {"published": True, "channel": "jobs", "task": input.task}
 
 
@@ -2135,7 +2153,7 @@ async def notification_publisher_workflow(
     """
     print(f"\n[PUBLISHER] Publishing notification: {input.message}")
     await publish(ctx, "notifications", {"message": input.message})
-    print(f"[PUBLISHER] Notification published to 'notifications' channel")
+    print("[PUBLISHER] Notification published to 'notifications' channel")
     return {"published": True, "channel": "notifications", "message": input.message}
 
 
@@ -2194,7 +2212,7 @@ async def direct_message_sender_workflow(
 
     await send_to(ctx, input.target_instance_id, {"message": input.message})
 
-    print(f"[SENDER] Message sent!")
+    print("[SENDER] Message sent!")
     return DirectMessageSenderResult(
         sent=True,
         target_instance_id=input.target_instance_id,

{edda_framework-0.9.1 → edda_framework-0.11.0}/docs/api/reference.md

@@ -20,6 +20,14 @@
 
 ---
 
+## Instance Search
+
+### find_instances
+
+::: edda.EddaApp.find_instances
+
+---
+
 ## Timer Functions
 
 ### sleep

edda_framework-0.11.0/docs/core-features/events/postgres-notify.md

@@ -0,0 +1,166 @@
+# PostgreSQL LISTEN/NOTIFY
+
+Edda supports PostgreSQL's LISTEN/NOTIFY mechanism for near-instant event and message delivery. This optional feature significantly reduces latency compared to polling-based delivery.
+
+## Overview
+
+By default, Edda uses polling to check for new events and messages. With PostgreSQL LISTEN/NOTIFY enabled:
+
+- **Event delivery**: Near-instant (milliseconds) instead of polling interval
+- **Message delivery**: Near-instant instead of polling interval
+- **Database load**: Reduced polling queries
+- **Fallback**: Automatic fallback to polling if notifications are missed
+
+## Installation
+
+Install the `postgres-notify` extra:
+
+```bash
+# Using uv
+uv add edda-framework --extra postgres-notify
+
+# Using pip
+pip install "edda-framework[postgres-notify]"
+```
+
+This installs `asyncpg`, which is required for LISTEN/NOTIFY support.
+
+## Configuration
+
+### Basic Usage (Auto-detection)
+
+```python
+from edda import EddaApp
+
+# LISTEN/NOTIFY is auto-detected for PostgreSQL
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://user:password@localhost/workflows",
+)
+```
+
+When using PostgreSQL, LISTEN/NOTIFY is automatically enabled if `asyncpg` is installed.
+
+### Explicit Configuration
+
+```python
+from edda import EddaApp
+
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://user:password@localhost/workflows",
+    use_listen_notify=True,  # Force enable
+    notify_fallback_interval=30,  # Fallback polling every 30 seconds
+)
+```
+
+### Configuration Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `use_listen_notify` | `bool \| None` | `None` | Notification mode: `None` = auto-detect, `True` = force enable, `False` = force disable |
+| `notify_fallback_interval` | `int` | `30` | Fallback polling interval in seconds when NOTIFY is enabled |
+| `max_workflows_per_batch` | `int \| "auto" \| "auto:cpu"` | `10` | Workflows per resume cycle. `"auto"` scales by queue depth, `"auto:cpu"` by CPU usage |
+
+### Auto-detection Behavior
+
+| Database | `use_listen_notify=None` | `use_listen_notify=True` | `use_listen_notify=False` |
+|----------|--------------------------|--------------------------|---------------------------|
+| PostgreSQL | Enabled (if asyncpg installed) | Enabled (error if asyncpg missing) | Disabled (polling only) |
+| MySQL | Disabled | Error | Disabled |
+| SQLite | Disabled | Error | Disabled |
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────┐     NOTIFY      ┌─────────────────┐
+│   Worker Pod 1  │ <────────────── │    PostgreSQL   │
+│   (Edda App)    │                 │    Database     │
+└─────────────────┘                 └─────────────────┘
+         │                                   │
+         │         LISTEN                    │
+         └───────────────────────────────────┘
+```
+
+1. **Dedicated Connection**: Edda maintains a separate asyncpg connection for LISTEN/NOTIFY
+2. **Channel Subscription**: Subscribes to notification channels on startup
+3. **Instant Wakeup**: When a notification arrives, waiting workflows are immediately resumed
+4. **Fallback Polling**: Periodic polling ensures no notifications are missed
+
+### Notification Channels
+
+Edda uses the following PostgreSQL channels:
+
+- `edda_workflow_resume`: Notifies when workflows should be resumed
+- `edda_outbox_ready`: Notifies when outbox events are ready for relay
+
+## Performance Comparison
+
+| Metric | Polling Only | With LISTEN/NOTIFY |
+|--------|--------------|-------------------|
+| Event delivery latency | 0.5-1s (polling interval) | ~10-50ms |
+| Message delivery latency | 0.5-1s | ~10-50ms |
+| Database queries per idle workflow | Every 1s | Every 30s (fallback only) |
+| Connection overhead | 1 per pool | +1 dedicated LISTEN connection |
+
+## Reliability Features
+
+### Automatic Reconnection
+
+The LISTEN connection automatically reconnects on failure with configurable retry settings.
+
+### Fallback Polling
+
+Even with NOTIFY enabled, Edda maintains fallback polling:
+
+- **Default interval**: 30 seconds (`notify_fallback_interval`)
+- **Purpose**: Catch any missed notifications
+- **Behavior**: Polling runs in parallel with NOTIFY
+
+## Troubleshooting
+
+### asyncpg Not Installed
+
+If you see a warning about asyncpg not being installed:
+
+```
+WARNING: asyncpg not installed, falling back to polling-only mode.
+Install with: pip install edda-framework[postgres-notify]
+```
+
+**Solution**: Install the postgres-notify extra.
+
+### Force Enable on Non-PostgreSQL
+
+If you see an error about LISTEN/NOTIFY requiring PostgreSQL:
+
+```
+ValueError: use_listen_notify=True requires PostgreSQL database.
+```
+
+**Solution**: Use `use_listen_notify=None` (auto-detect) or `False` for non-PostgreSQL databases.
+
+### Connection Lost
+
+If you see reconnection messages in logs:
+
+```
+INFO: Connection lost, attempting reconnection...
+```
+
+This is normal behavior. Edda automatically reconnects, and workflows continue with polling fallback during reconnection.
+
+## Best Practices
+
+1. **Use auto-detection**: Set `use_listen_notify=None` (default) for portability across different database backends
+2. **Install postgres-notify in production**: For best performance with PostgreSQL
+3. **Monitor reconnections**: Frequent reconnection warnings may indicate network issues
+4. **Adjust fallback interval**: Lower values provide more reliability but increase database load
+
+## Related Topics
+
+- [Event Waiting](wait-event.md) - How workflows wait for events
+- [Channel-based Messaging](../messages.md) - Workflow-to-workflow communication
+- [Installation](../../getting-started/installation.md) - Database setup

{edda_framework-0.9.1 → edda_framework-0.11.0}/docs/getting-started/installation.md

@@ -38,6 +38,9 @@ uv add edda-framework --extra mysql
 # With Viewer UI (workflow visualization)
 uv add edda-framework --extra viewer
 
+# With PostgreSQL instant notifications (LISTEN/NOTIFY)
+uv add edda-framework --extra postgres-notify
+
 # All extras (PostgreSQL + MySQL + Viewer UI)
 uv add edda-framework --extra postgresql --extra mysql --extra viewer
 ```
@@ -48,6 +51,7 @@ uv add edda-framework --extra postgresql --extra mysql --extra viewer
 - **postgresql**: `asyncpg` driver for PostgreSQL
 - **mysql**: `aiomysql` driver for MySQL
 - **viewer**: `nicegui` and `httpx` for workflow visualization UI
+- **postgres-notify**: `asyncpg` driver for PostgreSQL LISTEN/NOTIFY instant notifications
 
 ### Using pip
 
@@ -66,6 +70,9 @@ pip install "edda-framework[mysql]"
 # With Viewer UI
 pip install "edda-framework[viewer]"
 
+# With PostgreSQL instant notifications
+pip install "edda-framework[postgres-notify]"
+
 # All extras
 pip install "edda-framework[postgresql,mysql,viewer]"
 ```
@@ -244,6 +251,44 @@ app = EddaApp(
 )
 ```
 
+#### Enabling Instant Notifications (LISTEN/NOTIFY)
+
+For near-instant event and message delivery, enable PostgreSQL LISTEN/NOTIFY:
+
+```bash
+# Install the postgres-notify extra
+uv add edda-framework --extra postgres-notify
+# or
+pip install "edda-framework[postgres-notify]"
+```
+
+```python
+from edda import EddaApp
+
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://user:password@localhost/edda_workflows",
+    use_listen_notify=True,  # Enable LISTEN/NOTIFY (auto-detected by default)
+    notify_fallback_interval=30,  # Fallback polling interval in seconds
+)
+```
+
+**Configuration options:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `use_listen_notify` | `bool \| None` | `None` | `None` = auto-detect (enabled for PostgreSQL), `True` = force enable, `False` = force disable |
+| `notify_fallback_interval` | `int` | `30` | Fallback polling interval in seconds when NOTIFY is enabled |
+
+**Benefits:**
+
+- Near-instant event delivery (milliseconds vs. seconds with polling)
+- Reduced database load (fewer polling queries)
+- Automatic fallback to polling if NOTIFY fails
+- Automatic reconnection on connection loss
+
+See [PostgreSQL LISTEN/NOTIFY](../core-features/events/postgres-notify.md) for detailed documentation.
+
 ### MySQL
 
 1. **Install MySQL** (if not already installed)

{edda_framework-0.9.1 → edda_framework-0.11.0}/docs/index.md

@@ -27,6 +27,7 @@ Edda is a lightweight durable execution framework for Python that runs as a **li
 - ☁️ **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
 - 📬 **Message Passing**: Channel-based messaging (broadcast/competing modes) and direct workflow-to-workflow communication
+- ⚡ **Instant Notifications**: Optional PostgreSQL LISTEN/NOTIFY for near-instant event delivery
 
 ## Use Cases