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

{edda_framework-0.4.0 → edda_framework-0.6.0}/.github/workflows/ci.yml

@@ -53,8 +53,8 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
-      - name: Install dependencies (all database drivers)
-        run: uv sync --extra dev --extra postgresql --extra mysql
+      - name: Install dependencies (all database drivers and opentelemetry)
+        run: uv sync --extra dev --extra postgresql --extra mysql --extra opentelemetry
 
       - name: Run tests (all databases)
         env:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.4.0
+Version: 0.6.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -42,6 +42,10 @@ Provides-Extra: mcp
 Requires-Dist: mcp>=1.22.0; extra == 'mcp'
 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: postgresql
 Requires-Dist: asyncpg>=0.30.0; extra == 'postgresql'
 Provides-Extra: server
@@ -91,6 +95,28 @@ Edda excels at orchestrating **long-running workflows** that must survive failur
 - **🤖 AI Agent Workflows**: Orchestrate multi-step AI tasks (LLM calls, tool usage, long-running inference)
 - **📡 Event-Driven Workflows**: React to external events with guaranteed delivery and automatic retry
 
+### Business Process Automation
+
+Edda's waiting functions make it ideal for time-based and event-driven business processes:
+
+- **📧 User Onboarding**: Send reminders if users haven't completed setup after N days
+- **🎁 Campaign Processing**: Evaluate conditions and notify winners after campaign ends
+- **💳 Payment Reminders**: Send escalating reminders before payment deadlines
+- **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
+
+**Waiting functions**:
+- `wait_timer(duration_seconds)`: Wait for a relative duration
+- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `wait_event(event_type)`: Wait for external events (near real-time response)
+
+```python
+@workflow
+async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
+    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    if not await check_completed(ctx, user_id):
+        await send_reminder(ctx, user_id)
+```
+
 **Key benefit**: Workflows **never lose progress** - crashes and restarts are handled automatically through deterministic replay.
 
 ## Architecture
@@ -683,7 +709,7 @@ def process_payment(ctx: WorkflowContext, amount: float) -> dict:
 @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")
+    result = await process_payment(ctx, 99.99)
     return result
 ```
 
@@ -722,13 +748,14 @@ if __name__ == "__main__":
 
 ### Auto-Generated Tools
 
-Each `@durable_tool` automatically generates **three MCP tools**:
+Each `@durable_tool` automatically generates **four MCP tools**:
 
 1. **Main tool** (`process_order`): Starts the workflow, returns instance ID
-2. **Status tool** (`process_order_status`): Checks workflow progress
+2. **Status tool** (`process_order_status`): Checks workflow progress with completed activity count and suggested poll interval
 3. **Result tool** (`process_order_result`): Gets final result when completed
+4. **Cancel tool** (`process_order_cancel`): Cancels workflow if running or waiting, executes compensation handlers
 
-This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
+This enables AI assistants to work with workflows that take minutes, hours, or even days to complete, with full control over the workflow lifecycle.
 
 ### MCP Prompts
 

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

@@ -39,6 +39,28 @@ Edda excels at orchestrating **long-running workflows** that must survive failur
 - **🤖 AI Agent Workflows**: Orchestrate multi-step AI tasks (LLM calls, tool usage, long-running inference)
 - **📡 Event-Driven Workflows**: React to external events with guaranteed delivery and automatic retry
 
+### Business Process Automation
+
+Edda's waiting functions make it ideal for time-based and event-driven business processes:
+
+- **📧 User Onboarding**: Send reminders if users haven't completed setup after N days
+- **🎁 Campaign Processing**: Evaluate conditions and notify winners after campaign ends
+- **💳 Payment Reminders**: Send escalating reminders before payment deadlines
+- **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
+
+**Waiting functions**:
+- `wait_timer(duration_seconds)`: Wait for a relative duration
+- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `wait_event(event_type)`: Wait for external events (near real-time response)
+
+```python
+@workflow
+async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
+    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    if not await check_completed(ctx, user_id):
+        await send_reminder(ctx, user_id)
+```
+
 **Key benefit**: Workflows **never lose progress** - crashes and restarts are handled automatically through deterministic replay.
 
 ## Architecture
@@ -631,7 +653,7 @@ def process_payment(ctx: WorkflowContext, amount: float) -> dict:
 @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")
+    result = await process_payment(ctx, 99.99)
     return result
 ```
 
@@ -670,13 +692,14 @@ if __name__ == "__main__":
 
 ### Auto-Generated Tools
 
-Each `@durable_tool` automatically generates **three MCP tools**:
+Each `@durable_tool` automatically generates **four MCP tools**:
 
 1. **Main tool** (`process_order`): Starts the workflow, returns instance ID
-2. **Status tool** (`process_order_status`): Checks workflow progress
+2. **Status tool** (`process_order_status`): Checks workflow progress with completed activity count and suggested poll interval
 3. **Result tool** (`process_order_result`): Gets final result when completed
+4. **Cancel tool** (`process_order_cancel`): Cancels workflow if running or waiting, executes compensation handlers
 
-This enables AI assistants to work with workflows that take minutes, hours, or even days to complete.
+This enables AI assistants to work with workflows that take minutes, hours, or even days to complete, with full control over the workflow lifecycle.
 
 ### MCP Prompts
 

{edda_framework-0.4.0 → edda_framework-0.6.0}/docs/core-features/hooks.md

@@ -30,9 +30,10 @@ class LogfireHooks(HooksBase):
             instance_id=instance_id,
             workflow_name=workflow_name)
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         logfire.info("activity.complete",
             instance_id=instance_id,
+            activity_id=activity_id,
             activity_name=activity_name,
             cache_hit=cache_hit
         )
@@ -69,9 +70,9 @@ The `WorkflowHooks` Protocol defines these methods (all optional):
 | `on_workflow_complete` | `instance_id`, `workflow_name`, `result` | Called when a workflow completes successfully |
 | `on_workflow_failed` | `instance_id`, `workflow_name`, `error` | Called when a workflow fails with an exception |
 | `on_workflow_cancelled` | `instance_id`, `workflow_name` | Called when a workflow is cancelled |
-| `on_activity_start` | `instance_id`, `step`, `activity_name`, `is_replaying` | Called before an activity executes |
-| `on_activity_complete` | `instance_id`, `step`, `activity_name`, `result`, `cache_hit` | Called after an activity completes successfully |
-| `on_activity_failed` | `instance_id`, `step`, `activity_name`, `error` | Called when an activity fails with an exception |
+| `on_activity_start` | `instance_id`, `activity_id`, `activity_name`, `is_replaying` | Called before an activity executes |
+| `on_activity_complete` | `instance_id`, `activity_id`, `activity_name`, `result`, `cache_hit` | Called after an activity completes successfully |
+| `on_activity_failed` | `instance_id`, `activity_id`, `activity_name`, `error` | Called when an activity fails with an exception |
 | `on_event_sent` | `event_type`, `event_source`, `event_data` | Called when an event is sent (transactional outbox) |
 | `on_event_received` | `instance_id`, `event_type`, `event_data` | Called when a workflow receives an awaited event |
 
@@ -150,8 +151,9 @@ class LogfireHooks(HooksBase):
             instance_id=instance_id,
             workflow_name=workflow_name)
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         logfire.info("activity.complete",
+            activity_id=activity_id,
             activity_name=activity_name,
             cache_hit=cache_hit)
 
@@ -181,7 +183,7 @@ class DatadogHooks(HooksBase):
             span.set_tag("workflow.name", workflow_name)
             span.set_tag("instance.id", instance_id)
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         statsd.increment('edda.activity.completed',
             tags=[f'activity:{activity_name}', f'cache_hit:{cache_hit}'])
 ```
@@ -199,7 +201,7 @@ class PrometheusHooks(HooksBase):
     async def on_workflow_start(self, instance_id, workflow_name, input_data):
         workflow_started.labels(workflow_name=workflow_name).inc()
 
-    async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
+    async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
         activity_executed.labels(activity_name=activity_name, cache_hit=str(cache_hit)).inc()
 ```
 
@@ -218,17 +220,50 @@ class SentryHooks(HooksBase):
             })
             sentry_sdk.capture_exception(error)
 
-    async def on_activity_failed(self, instance_id, step, activity_name, error):
+    async def on_activity_failed(self, instance_id, activity_id, activity_name, error):
         with sentry_sdk.push_scope() as scope:
             scope.set_context("activity", {
                 "instance_id": instance_id,
+                "activity_id": activity_id,
                 "activity_name": activity_name,
             })
             sentry_sdk.capture_exception(error)
 ```
 
+### OpenTelemetry (Official Integration)
+
+Edda provides an official OpenTelemetry integration with full tracing, optional metrics, and W3C Trace Context propagation.
+
+```python
+from edda import EddaApp
+from edda.integrations.opentelemetry import OpenTelemetryHooks
+
+hooks = OpenTelemetryHooks(
+    service_name="order-service",
+    otlp_endpoint="http://localhost:4317",  # Optional
+    enable_metrics=True,  # Optional
+)
+
+app = EddaApp(
+    service_name="order-service",
+    db_url="sqlite:///workflow.db",
+    hooks=hooks,
+)
+```
+
+**Features:**
+
+- ✅ Distributed tracing with parent-child span relationships
+- ✅ Optional metrics (counters, histograms)
+- ✅ W3C Trace Context propagation via CloudEvents
+- ✅ Automatic context inheritance from ASGI/WSGI middleware
+
+👉 **See [OpenTelemetry Integration](../integrations/opentelemetry.md) for full documentation.**
+
 ## See Also
 
+- **[OpenTelemetry Integration](../integrations/opentelemetry.md)**: Official OpenTelemetry integration with full documentation
 - **[Complete Logfire Example](https://github.com/i2y/edda/blob/main/examples/observability_with_logfire.py)**: Full implementation with multiple workflows
+- **[Complete OpenTelemetry Example](https://github.com/i2y/edda/blob/main/examples/observability_with_opentelemetry.py)**: Full implementation with tracing, optional metrics, and CloudEvents context propagation
 - **[Observability Guide](https://github.com/i2y/edda/blob/main/examples/README_observability.md)**: Detailed guide with more integration examples
 - **[API Reference](https://github.com/i2y/edda/blob/main/edda/hooks.py)**: WorkflowHooks Protocol definition

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

@@ -36,6 +36,28 @@ Edda excels at orchestrating **long-running workflows** that must survive failur
 - **🤖 AI Agent Workflows**: Orchestrate multi-step AI tasks (LLM calls, tool usage, long-running inference)
 - **📡 Event-Driven Workflows**: React to external events with guaranteed delivery and automatic retry
 
+### Business Process Automation
+
+Edda's waiting functions make it ideal for time-based and event-driven business processes:
+
+- **📧 User Onboarding**: Send reminders if users haven't completed setup after N days
+- **🎁 Campaign Processing**: Evaluate conditions and notify winners after campaign ends
+- **💳 Payment Reminders**: Send escalating reminders before payment deadlines
+- **📦 Scheduled Notifications**: Shipping updates, subscription renewals, appointment reminders
+
+**Waiting functions**:
+- `wait_timer(duration_seconds)`: Wait for a relative duration
+- `wait_until(until_time)`: Wait until an absolute datetime (e.g., campaign end date)
+- `wait_event(event_type)`: Wait for external events (near real-time response)
+
+```python
+@workflow
+async def onboarding_reminder(ctx: WorkflowContext, user_id: str):
+    await wait_timer(ctx, duration_seconds=3*24*60*60)  # Wait 3 days
+    if not await check_completed(ctx, user_id):
+        await send_reminder(ctx, user_id)
+```
+
 **Key benefit**: Workflows **never lose progress** - crashes and restarts are handled automatically through deterministic replay.
 
 ## Architecture

{edda_framework-0.4.0 → edda_framework-0.6.0}/docs/integrations/mcp.md

@@ -7,10 +7,11 @@ Edda provides seamless integration with the [Model Context Protocol (MCP)](https
 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
+- **Check workflow status** to monitor progress with completed activity count and suggested poll interval
 - **Retrieve results** when workflows complete
+- **Cancel workflows** if running or waiting, with automatic compensation execution
 
-This enables AI assistants to work with long-running processes that may take minutes, hours, or even days to complete.
+This enables AI assistants to work with long-running processes that may take minutes, hours, or even days to complete, with full control over the workflow lifecycle.
 
 ## Installation
 
@@ -97,7 +98,7 @@ Add to your MCP client configuration (e.g., Claude Desktop: `~/Library/Applicati
 
 ## Auto-Generated Tools
 
-Each `@durable_tool` automatically generates **three MCP tools**:
+Each `@durable_tool` automatically generates **four MCP tools**:
 
 ### 1. Main Tool: Start Workflow
 
@@ -125,12 +126,16 @@ Input: {"instance_id": "abc123..."}
 Output: {
   "content": [{
     "type": "text",
-    "text": "Workflow Status: running\nCurrent Activity: payment:1\nInstance ID: abc123..."
+    "text": "Workflow Status: running\nCurrent Activity: payment:1\nCompleted Activities: 1\nSuggested Poll Interval: 5000ms\nInstance ID: abc123..."
   }],
   "isError": false
 }
 ```
 
+The status tool provides progress metadata for efficient polling:
+- **Completed Activities**: Number of activities that have finished
+- **Suggested Poll Interval**: Recommended wait time before checking again (5000ms for running, 10000ms for waiting)
+
 ### 3. Result Tool: Get Final Result
 
 ```
@@ -147,6 +152,27 @@ Output: {
 }
 ```
 
+### 4. Cancel Tool: Stop Workflow
+
+```
+Tool Name: process_order_cancel
+Description: Cancel process_order workflow (if running or waiting)
+
+Input: {"instance_id": "abc123..."}
+Output: {
+  "content": [{
+    "type": "text",
+    "text": "Workflow 'process_order' cancelled successfully.\nInstance ID: abc123...\nCompensations executed.\n\nThe workflow has been stopped and any side effects have been rolled back."
+  }],
+  "isError": false
+}
+```
+
+The cancel tool:
+- Only works on workflows with status `running`, `waiting_for_event`, or `waiting_for_timer`
+- Automatically executes SAGA compensation transactions to roll back side effects
+- Returns an error for already completed, failed, or cancelled workflows
+
 ## Advanced Configuration
 
 ### Authentication

edda_framework-0.6.0/docs/integrations/opentelemetry.md

@@ -0,0 +1,179 @@
+# OpenTelemetry Integration
+
+Edda provides official integration with [OpenTelemetry](https://opentelemetry.io/), enabling distributed tracing and optional metrics for your durable workflows.
+
+## Overview
+
+OpenTelemetry is an industry-standard observability framework. Edda's OpenTelemetry integration provides:
+
+- **Distributed Tracing**: Workflow and activity spans with parent-child relationships
+- **Optional Metrics**: Counters for workflow/activity execution, histograms for duration
+- **W3C Trace Context**: Propagate traces across service boundaries via CloudEvents
+- **Automatic Context Inheritance**: Inherit from ASGI/WSGI middleware or CloudEvents headers
+
+## Installation
+
+Install Edda with OpenTelemetry support:
+
+```bash
+pip install edda-framework[opentelemetry]
+
+# Or using uv
+uv add edda-framework --extra opentelemetry
+```
+
+## Quick Start
+
+```python
+from edda import EddaApp, workflow, activity, WorkflowContext
+from edda.integrations.opentelemetry import OpenTelemetryHooks
+
+# Create hooks (console exporter for development)
+hooks = OpenTelemetryHooks(
+    service_name="order-service",
+    otlp_endpoint=None,  # Use console exporter
+    enable_metrics=False,
+)
+
+# Or with OTLP exporter for production (Jaeger, Tempo, etc.)
+hooks = OpenTelemetryHooks(
+    service_name="order-service",
+    otlp_endpoint="http://localhost:4317",
+    enable_metrics=True,
+)
+
+app = EddaApp(
+    service_name="order-service",
+    db_url="sqlite:///workflow.db",
+    hooks=hooks,
+)
+
+@activity
+async def reserve_inventory(ctx: WorkflowContext, order_id: str):
+    return {"reserved": True}
+
+@workflow
+async def order_workflow(ctx: WorkflowContext, order_id: str):
+    await reserve_inventory(ctx, order_id)
+    return {"status": "completed"}
+
+async def main():
+    await app.initialize()
+    await order_workflow.start(order_id="ORD-123")
+```
+
+## Span Hierarchy
+
+Edda creates a hierarchical span structure:
+
+```
+workflow:order_workflow (parent)
+├── activity:reserve_inventory:1 (child)
+├── activity:process_payment:1 (child)
+└── activity:ship_order:1 (child)
+```
+
+## Span Attributes
+
+**Workflow Spans**:
+- `edda.workflow.instance_id`
+- `edda.workflow.name`
+- `edda.workflow.cancelled` (when cancelled)
+
+**Activity Spans**:
+- `edda.activity.id` (e.g., "reserve_inventory:1")
+- `edda.activity.name`
+- `edda.activity.is_replaying`
+- `edda.activity.cache_hit`
+
+## Metrics (Optional)
+
+When `enable_metrics=True`:
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `edda.workflow.started` | Counter | Workflows started |
+| `edda.workflow.completed` | Counter | Workflows completed |
+| `edda.workflow.failed` | Counter | Workflows failed |
+| `edda.workflow.duration` | Histogram | Workflow execution time |
+| `edda.activity.executed` | Counter | Activities executed |
+| `edda.activity.cache_hit` | Counter | Activity cache hits |
+| `edda.activity.duration` | Histogram | Activity execution time |
+
+## Trace Context Propagation
+
+### Automatic Context Inheritance
+
+OpenTelemetryHooks automatically inherits trace context from multiple sources, with the following priority:
+
+1. **Explicit `_trace_context` in input_data** (highest priority)
+   - Extracted from CloudEvents extension attributes
+   - Useful for cross-service trace propagation
+
+2. **Current active span** (e.g., from ASGI/WSGI middleware)
+   - Automatically detected using `trace.get_current_span()`
+   - Works with OpenTelemetry instrumentation middleware
+
+3. **New root span** (if no parent context is found)
+
+### CloudEvents Integration
+
+Inject trace context when sending events:
+
+```python
+from edda.integrations.opentelemetry import inject_trace_context
+
+event_data = {"order_id": "ORD-123"}
+event_data = inject_trace_context(hooks, ctx.instance_id, event_data)
+await send_event_transactional(ctx, "order.shipped", "orders", event_data)
+```
+
+When a CloudEvent contains W3C Trace Context extension attributes (`traceparent`, `tracestate`), they are automatically extracted and used as the parent context:
+
+```bash
+# CloudEvent with trace context
+curl -X POST http://localhost:8001/ \
+  -H "Content-Type: application/json" \
+  -H "ce-specversion: 1.0" \
+  -H "ce-type: order.created" \
+  -H "ce-source: external-service" \
+  -H "ce-id: event-123" \
+  -H "ce-traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" \
+  -d '{"order_id": "ORD-123"}'
+```
+
+### ASGI/WSGI Middleware
+
+OpenTelemetryHooks automatically inherits from the current active span:
+
+```python
+from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
+
+# Middleware creates parent span for each HTTP request
+app = OpenTelemetryMiddleware(edda_app)
+
+# Workflow spans automatically inherit from the request span
+```
+
+### Existing TracerProvider Reuse
+
+If a TracerProvider is already configured (e.g., by ASGI middleware or your application), OpenTelemetryHooks will reuse it instead of creating a new one:
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+
+# Configure your own provider
+provider = TracerProvider(resource=my_resource)
+trace.set_tracer_provider(provider)
+
+# OpenTelemetryHooks will use the existing provider
+hooks = OpenTelemetryHooks(service_name="my-service")
+# No new provider is created!
+```
+
+## Related Documentation
+
+- [Lifecycle Hooks](../core-features/hooks.md) - Detailed hooks documentation
+- [Example](../../examples/observability_with_opentelemetry.py) - Complete working example
+- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)

{edda_framework-0.4.0 → edda_framework-0.6.0}/edda/app.py

@@ -238,7 +238,9 @@ class EddaApp:
         Register a default CloudEvent handler for a workflow.
 
         The default handler extracts the CloudEvent data and passes it
-        as kwargs to workflow.start().
+        as kwargs to workflow.start(). If the CloudEvent contains
+        traceparent/tracestate extension attributes (for distributed tracing),
+        they are automatically injected into _trace_context.
 
         Args:
             event_type: CloudEvent type (same as workflow name)
@@ -250,11 +252,24 @@ class EddaApp:
             # Extract data from CloudEvent
             data = event.get_data()
 
+            # Extract trace context from CloudEvent extension attributes
+            # (W3C Trace Context: traceparent, tracestate)
+            trace_context: dict[str, str] = {}
+            attrs = event.get_attributes()
+            if "traceparent" in attrs:
+                trace_context["traceparent"] = str(attrs["traceparent"])
+            if "tracestate" in attrs:
+                trace_context["tracestate"] = str(attrs["tracestate"])
+
             # Start workflow with data as kwargs
             if isinstance(data, dict):
+                # Inject trace context if present
+                if trace_context:
+                    data = {**data, "_trace_context": trace_context}
                 await wf.start(**data)
             else:
                 # If data is not a dict, start without arguments
+                # (trace context cannot be injected)
                 await wf.start()
 
         # Register the handler

{edda_framework-0.4.0 → edda_framework-0.6.0}/edda/hooks.py

@@ -12,8 +12,8 @@ Example:
     ...     async def on_workflow_start(self, instance_id, workflow_name, input_data):
     ...         print(f"Workflow {workflow_name} started: {instance_id}")
     ...
-    ...     async def on_activity_complete(self, instance_id, step, activity_name, result, cache_hit):
-    ...         print(f"Activity {activity_name} completed (cache_hit={cache_hit})")
+    ...     async def on_activity_complete(self, instance_id, activity_id, activity_name, result, cache_hit):
+    ...         print(f"Activity {activity_name} ({activity_id}) completed (cache_hit={cache_hit})")
     >>>
     >>> app = EddaApp(service_name="my-service", db_url="...", hooks=MyHooks())
 """
@@ -86,7 +86,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_start(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         is_replaying: bool,
     ) -> None:
@@ -95,7 +95,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             is_replaying: True if this is a replay (cached result)
         """
@@ -104,7 +104,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_complete(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         result: Any,
         cache_hit: bool,
@@ -114,7 +114,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             result: Return value from the activity
             cache_hit: True if result was retrieved from cache (replay)
@@ -124,7 +124,7 @@ class WorkflowHooks(Protocol):
     async def on_activity_failed(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         error: Exception,
     ) -> None:
@@ -133,7 +133,7 @@ class WorkflowHooks(Protocol):
 
         Args:
             instance_id: Unique workflow instance ID
-            step: Step number in the workflow
+            activity_id: Activity ID (e.g., "reserve_inventory:1")
             activity_name: Name of the activity function
             error: Exception that caused the failure
         """
@@ -231,7 +231,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_start(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         is_replaying: bool,
     ) -> None:
@@ -240,7 +240,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_complete(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         result: Any,
         cache_hit: bool,
@@ -250,7 +250,7 @@ class HooksBase(WorkflowHooks, ABC):
     async def on_activity_failed(
         self,
         instance_id: str,
-        step: int,
+        activity_id: str,
         activity_name: str,
         error: Exception,
     ) -> None: