edda-framework 0.10.0__tar.gz → 0.12.0__tar.gz

{edda_framework-0.10.0 → edda_framework-0.12.0}/.github/workflows/ci.yml

@@ -45,7 +45,9 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v3

{edda_framework-0.10.0 → edda_framework-0.12.0}/.github/workflows/docs.yml

@@ -16,7 +16,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: Set up Python
         uses: actions/setup-python@v5

{edda_framework-0.10.0 → edda_framework-0.12.0}/.github/workflows/release.yml

@@ -17,7 +17,9 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          submodules: true
 
       - name: Set up uv
         uses: astral-sh/setup-uv@v3
@@ -29,7 +31,9 @@ jobs:
         run: uv sync
 
       - name: Build package
-        run: uv build
+        run: |
+          uv build --sdist
+          uv build --wheel
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1

edda_framework-0.12.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "schema"]
+	path = schema
+	url = https://github.com/durax-io/schema.git

{edda_framework-0.10.0 → edda_framework-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.10.0
+Version: 0.12.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -44,6 +44,9 @@ 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
@@ -93,6 +96,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📬 **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
@@ -282,6 +286,46 @@ pip install "git+https://github.com/i2y/edda.git[postgresql,viewer]"
 
 > **Tip**: For PostgreSQL, install the `postgres-notify` extra for near-instant event delivery using LISTEN/NOTIFY instead of polling.
 
+### Database Schema Migration
+
+**Automatic Migration (Default)**
+
+Edda automatically applies database migrations at startup. No manual commands needed:
+
+```python
+from edda import EddaApp
+
+# Migrations are applied automatically
+app = EddaApp(db_url="postgresql://user:pass@localhost/dbname")
+```
+
+This is safe in multi-worker environments - Edda handles concurrent startup gracefully.
+
+**Manual Migration with dbmate (Optional)**
+
+For explicit schema control, you can disable auto-migration and use [dbmate](https://github.com/amacneil/dbmate):
+
+```python
+# Disable auto-migration
+app = EddaApp(
+    db_url="postgresql://...",
+    auto_migrate=False  # Use dbmate-managed schema
+)
+```
+
+```bash
+# Install dbmate
+brew install dbmate  # macOS
+
+# Add schema submodule
+git submodule add https://github.com/durax-io/schema.git schema
+
+# Run migration manually
+DATABASE_URL="postgresql://user:pass@localhost/dbname" dbmate -d ./schema/db/migrations/postgresql up
+```
+
+> **Note**: Edda's auto-migration uses the same SQL files as dbmate, maintaining full compatibility.
+
 ### Development Installation
 
 If you want to contribute to Edda or modify the framework itself:
@@ -289,7 +333,7 @@ If you want to contribute to Edda or modify the framework itself:
 ```bash
 # Clone repository
 git clone https://github.com/i2y/edda.git
-cd kairo
+cd edda
 uv sync --all-extras
 ```
 
@@ -329,7 +373,7 @@ async def user_signup(ctx: WorkflowContext, email: str):
     return {"status": "completed"}
 ```
 
-**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`). See [MIGRATION_GUIDE_ACTIVITY_ID.md](MIGRATION_GUIDE_ACTIVITY_ID.md) for details.
+**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`).
 
 ### Durable Execution
 

{edda_framework-0.10.0 → edda_framework-0.12.0}/README.md

@@ -31,6 +31,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📬 **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
@@ -220,6 +221,46 @@ pip install "git+https://github.com/i2y/edda.git[postgresql,viewer]"
 
 > **Tip**: For PostgreSQL, install the `postgres-notify` extra for near-instant event delivery using LISTEN/NOTIFY instead of polling.
 
+### Database Schema Migration
+
+**Automatic Migration (Default)**
+
+Edda automatically applies database migrations at startup. No manual commands needed:
+
+```python
+from edda import EddaApp
+
+# Migrations are applied automatically
+app = EddaApp(db_url="postgresql://user:pass@localhost/dbname")
+```
+
+This is safe in multi-worker environments - Edda handles concurrent startup gracefully.
+
+**Manual Migration with dbmate (Optional)**
+
+For explicit schema control, you can disable auto-migration and use [dbmate](https://github.com/amacneil/dbmate):
+
+```python
+# Disable auto-migration
+app = EddaApp(
+    db_url="postgresql://...",
+    auto_migrate=False  # Use dbmate-managed schema
+)
+```
+
+```bash
+# Install dbmate
+brew install dbmate  # macOS
+
+# Add schema submodule
+git submodule add https://github.com/durax-io/schema.git schema
+
+# Run migration manually
+DATABASE_URL="postgresql://user:pass@localhost/dbname" dbmate -d ./schema/db/migrations/postgresql up
+```
+
+> **Note**: Edda's auto-migration uses the same SQL files as dbmate, maintaining full compatibility.
+
 ### Development Installation
 
 If you want to contribute to Edda or modify the framework itself:
@@ -227,7 +268,7 @@ If you want to contribute to Edda or modify the framework itself:
 ```bash
 # Clone repository
 git clone https://github.com/i2y/edda.git
-cd kairo
+cd edda
 uv sync --all-extras
 ```
 
@@ -267,7 +308,7 @@ async def user_signup(ctx: WorkflowContext, email: str):
     return {"status": "completed"}
 ```
 
-**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`). See [MIGRATION_GUIDE_ACTIVITY_ID.md](MIGRATION_GUIDE_ACTIVITY_ID.md) for details.
+**Activity IDs**: Activities are automatically identified with IDs like `"send_email:1"` for deterministic replay. Manual IDs are only needed for concurrent execution (e.g., `asyncio.gather`).
 
 ### Durable Execution
 

{edda_framework-0.10.0 → edda_framework-0.12.0}/docs/core-features/durable-execution/replay.md

@@ -349,7 +349,7 @@ async def resume_workflow_endpoint(instance_id: str):
 
 Edda automatically recovers from crashes in two stages:
 
-#### 3-1. Stale Lock Cleanup (Implemented)
+#### 3-1. Stale Lock Cleanup
 
 When a worker process crashes, its locks become "stale." Edda automatically cleans these up:
 
@@ -394,7 +394,7 @@ This background task starts automatically when `EddaApp` launches.
 
 The `status` field indicates whether the workflow was running normally (`"running"`) or executing compensations (`"compensating"`) when it crashed.
 
-#### 3-2. Automatic Workflow Resume (Implemented)
+#### 3-2. Automatic Workflow Resume
 
 After cleaning stale locks, Edda automatically resumes workflows with `status="running"` or `status="compensating"`:
 
@@ -586,6 +586,7 @@ async with workflow_lock(storage, instance_id, worker_id, timeout_seconds=300):
 ```
 
 Features:
+
 - **5-minute timeout** by default (prevents indefinite locks)
 - **Worker ID tracking** (know which worker holds the lock)
 - **Stale lock cleanup** (automatic recovery after crashes)

{edda_framework-0.10.0 → edda_framework-0.12.0}/docs/core-features/messages.md

@@ -47,6 +47,40 @@ async def notification_service(ctx: WorkflowContext, service_id: str):
 
 - `"broadcast"` (default): All subscribers receive all messages. Use for fan-out patterns like notifications.
 - `"competing"`: Each message is processed by only one subscriber. Use for job queues and task distribution.
+- `"direct"`: Receive messages sent via `send_to()` to this specific instance. Syntactic sugar for point-to-point messaging.
+
+**Using `mode="direct"`**:
+
+The `"direct"` mode simplifies receiving messages sent via `send_to()`:
+
+```python
+@workflow
+async def direct_receiver(ctx: WorkflowContext, id: str):
+    # Subscribe to receive direct messages
+    await subscribe(ctx, "notifications", mode="direct")
+
+    # Wait for a message sent via send_to()
+    msg = await receive(ctx, "notifications")
+    return msg.data
+
+@workflow
+async def sender(ctx: WorkflowContext, receiver_id: str):
+    # Send directly to the receiver instance
+    await send_to(ctx, instance_id=receiver_id, data={"hello": "world"}, channel="notifications")
+```
+
+This is equivalent to manually constructing the channel name:
+
+```python
+# Without mode="direct" (manual approach)
+direct_channel = f"notifications:{ctx.instance_id}"
+await subscribe(ctx, direct_channel, mode="broadcast")
+msg = await receive(ctx, direct_channel)
+
+# With mode="direct" (simplified)
+await subscribe(ctx, "notifications", mode="direct")
+msg = await receive(ctx, "notifications")
+```
 
 #### `unsubscribe()`
 
@@ -202,7 +236,7 @@ async def subscribe(
 
 - `ctx`: Workflow context
 - `channel`: Channel name to subscribe to
-- `mode`: `"broadcast"` (all subscribers receive) or `"competing"` (one subscriber per message)
+- `mode`: `"broadcast"` (all subscribers receive), `"competing"` (one subscriber per message), or `"direct"` (receive messages from `send_to()`)
 
 ### receive()
 

{edda_framework-0.10.0 → edda_framework-0.12.0}/docs/getting-started/installation.md

@@ -310,6 +310,88 @@ app = EddaApp(
 )
 ```
 
+### Schema Migration
+
+#### Automatic Migration (Default)
+
+Edda automatically applies database migrations at startup. No manual commands needed:
+
+```python
+from edda import EddaApp
+
+# Migrations are applied automatically at startup
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://user:pass@localhost/dbname"
+)
+```
+
+**Key features:**
+
+- **Zero configuration**: Works out of the box
+- **Multi-worker safe**: Handles concurrent startup gracefully (race condition protected)
+- **dbmate compatible**: Uses the same SQL files and `schema_migrations` table
+- **Incremental**: Only applies pending migrations
+
+#### Manual Migration with dbmate (Optional)
+
+For explicit schema control, you can disable auto-migration and use [dbmate](https://github.com/amacneil/dbmate):
+
+```python
+# Disable auto-migration
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://...",
+    auto_migrate=False  # Use dbmate-managed schema
+)
+```
+
+```bash
+# Install dbmate
+brew install dbmate  # macOS
+# Linux: curl -fsSL https://github.com/amacneil/dbmate/releases/latest/download/dbmate-linux-amd64 -o /usr/local/bin/dbmate && chmod +x /usr/local/bin/dbmate
+
+# Add schema submodule to your project
+git submodule add https://github.com/durax-io/schema.git schema
+
+# Run migration manually
+DATABASE_URL="postgresql://user:pass@localhost/dbname" dbmate -d ./schema/db/migrations/postgresql up
+
+# Check status
+dbmate -d ./schema/db/migrations/postgresql status
+```
+
+> **Note**: Edda's auto-migration uses the same SQL files as dbmate, so you can switch between modes freely.
+
+### Multi-Worker Configuration
+
+When running multiple Edda workers (e.g., in Kubernetes or with multiple processes), Edda automatically coordinates background tasks using **leader election**. Only one worker runs maintenance tasks (timers, message cleanup, etc.) while others focus on workflow execution.
+
+```python
+from edda import EddaApp
+
+app = EddaApp(
+    service_name="demo-service",
+    db_url="postgresql://...",
+    # Leader election settings (optional - defaults work well for most cases)
+    leader_heartbeat_interval=15,  # How often workers check/renew leadership
+    leader_lease_duration=45,      # How long before a failed leader is replaced
+)
+```
+
+**Configuration options:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `leader_heartbeat_interval` | `int` | `15` | Interval in seconds for leader heartbeat |
+| `leader_lease_duration` | `int` | `45` | Duration in seconds before leadership expires |
+
+**Notes:**
+
+- Default values work well for most deployments
+- Reduce `leader_lease_duration` for faster failover (minimum: 3x heartbeat interval)
+- Leader election uses the database for coordination (no external dependencies)
+
 ## Next Steps
 
 - **[Quick Start](quick-start.md)**: Build your first workflow in 5 minutes