pyworkflow-engine 0.2.14__tar.gz → 0.3.0__tar.gz

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyworkflow-engine
-Version: 0.2.14
+Version: 0.3.0
 Summary: A Python implementation of durable, event-sourced workflows inspired by Vercel Workflow
 Author: PyWorkflow Contributors
 License: MIT

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = [{include = "pyworkflow"}]
 
 [project]
 name = "pyworkflow-engine"
-version = "0.2.14"
+version = "0.3.0"
 description = "A Python implementation of durable, event-sourced workflows inspired by Vercel Workflow"
 readme = "README.md"
 requires-python = ">=3.11"

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/__init__.py

@@ -29,7 +29,7 @@ Quick Start:
     >>> run_id = await start(my_workflow, "Alice")
 """
 
-__version__ = "0.2.14"
+__version__ = "0.3.0"
 
 # Configuration
 from pyworkflow.config import (

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/celery/tasks.py

@@ -10,6 +10,7 @@ These tasks enable:
 """
 
 import asyncio
+import hashlib
 import random
 import uuid
 from collections.abc import Callable
@@ -93,6 +94,8 @@ def execute_step_task(
     context_data: dict[str, Any] | None = None,
     context_class_name: str | None = None,
     workflow_name: str | None = None,
+    tracing: dict[str, Any] | None = None,
+    is_generator: bool = False,
 ) -> Any:
     """
     Execute a workflow step on a Celery worker.
@@ -242,6 +245,7 @@ def execute_step_task(
             step_workflow_ctx._runtime = "celery"
             step_workflow_ctx._storage_config = storage_config
             step_workflow_ctx._is_step_worker = True
+            step_workflow_ctx.tracing = tracing
 
             # Set parent_run_id if this workflow is a child
             wf_run = run_async(storage.get_run(run_id))
@@ -284,6 +288,26 @@ def execute_step_task(
             step_id=step_id,
         )
 
+        # Record tracing span for this step on the worker
+        if tracing and result is not None:
+            try:
+                from pyworkflow.tracing import create_tracing_provider
+
+                _tp = create_tracing_provider(tracing)
+                if _tp:
+                    _tp.record_step_span(
+                        trace_id=hashlib.md5(run_id.encode()).hexdigest(),
+                        step_name=step_name,
+                        step_id=step_id,
+                        is_generator=is_generator,
+                        result=result,
+                        step_input=dict(kwargs) if kwargs else None,
+                        trace_name=workflow_name or "workflow",
+                    )
+                    run_async(_tp.shutdown())
+            except Exception:
+                pass  # Never fail step because of tracing
+
         # Record STEP_COMPLETED event and trigger workflow resumption
         run_async(
             _record_step_completion_and_resume(
@@ -580,6 +604,15 @@ async def _record_step_completion_and_resume(
     )
     await storage.record_event(completion_event)
 
+    # Release the resume_workflow_task singleton lock before scheduling the
+    # next resume. The parent resume task that dispatched this step may still
+    # be holding the (run_id,) lock during its final teardown; without this
+    # release the apply_async below sees the lock held and silently drops
+    # the schedule as a duplicate, leaving the workflow stuck in SUSPENDED.
+    resume_workflow_task.release_lock(
+        task_args=[run_id], task_kwargs={"storage_config": storage_config}
+    )
+
     # Schedule workflow resumption
     schedule_workflow_resumption(
         run_id, datetime.now(UTC), storage_config, triggered_by="step_completed"
@@ -769,6 +802,12 @@ async def _record_step_failure_and_resume(
     )
     await storage.record_event(failure_event)
 
+    # Release the resume_workflow_task singleton lock before scheduling the
+    # next resume (see _record_step_completion_and_resume for details on why).
+    resume_workflow_task.release_lock(
+        task_args=[run_id], task_kwargs={"storage_config": storage_config}
+    )
+
     # Schedule workflow resumption
     schedule_workflow_resumption(
         run_id, datetime.now(UTC), storage_config, triggered_by="step_failed"
@@ -840,6 +879,7 @@ def start_workflow_task(
     run_id: str,
     storage_config: dict[str, Any] | None = None,
     idempotency_key: str | None = None,
+    tracing: dict[str, Any] | None = None,
 ) -> str:
     """
     Start a workflow execution.
@@ -891,6 +931,7 @@ def start_workflow_task(
             storage_config=storage_config,
             idempotency_key=idempotency_key,
             run_id=run_id,
+            tracing=tracing,
         )
     )
 
@@ -1416,6 +1457,9 @@ async def _recover_workflow_on_worker(
     args = deserialize_args(run.input_args)
     kwargs = deserialize_kwargs(run.input_kwargs)
 
+    # Extract tracing config persisted at start
+    _recover_tracing = kwargs.pop("_tracing_config", None)
+
     # Execute workflow with event replay
     try:
         result = await execute_workflow_with_context(
@@ -1429,6 +1473,7 @@ async def _recover_workflow_on_worker(
             runtime="celery",
             storage_config=storage_config,
             parent_run_id=run.parent_run_id,
+            tracing=workflow_meta.tracing or _recover_tracing,
         )
 
         # Update run status to completed
@@ -1564,6 +1609,7 @@ async def _start_workflow_on_worker(
     storage_config: dict[str, Any] | None = None,
     idempotency_key: str | None = None,
     run_id: str | None = None,
+    tracing: dict[str, Any] | None = None,
 ) -> str:
     """
     Internal function to start workflow on Celery worker.
@@ -1764,10 +1810,10 @@ async def _start_workflow_on_worker(
         created_at=datetime.now(UTC),
         started_at=datetime.now(UTC),
         input_args=serialize_args(*args),
-        input_kwargs=serialize_kwargs(**kwargs),
+        input_kwargs=serialize_kwargs(**kwargs, _tracing_config=tracing),
         idempotency_key=idempotency_key,
         max_duration=workflow_meta.max_duration,
-        context={},  # Step context (not from decorator)
+        context={},  # Step context data
         recovery_attempts=0,
         max_recovery_attempts=max_recovery_attempts,
         recover_on_worker_loss=recover_on_worker_loss,
@@ -1797,6 +1843,7 @@ async def _start_workflow_on_worker(
             kwargs=kwargs,
             runtime="celery",
             storage_config=storage_config,
+            tracing=tracing or workflow_meta.tracing,
         )
 
         # Update run status to completed
@@ -2377,6 +2424,9 @@ async def _resume_workflow_on_worker(
     args = deserialize_args(run.input_args)
     kwargs = deserialize_kwargs(run.input_kwargs)
 
+    # Extract tracing config persisted at start
+    _resume_tracing = kwargs.pop("_tracing_config", None)
+
     # Execute workflow with event replay
     try:
         result = await execute_workflow_with_context(
@@ -2391,6 +2441,7 @@ async def _resume_workflow_on_worker(
             runtime="celery",
             storage_config=storage_config,
             parent_run_id=run.parent_run_id,
+            tracing=workflow_meta.tracing or _resume_tracing,
         )
 
         # Update run status to completed

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/config.py

@@ -171,6 +171,9 @@ class PyWorkflowConfig:
     event_hard_limit: int = 50_000  # Fail workflow at this count
     event_warning_interval: int = 100  # Log warning every N events after soft limit
 
+    # Tracing Configuration
+    TRACING_CONFIG: dict | None = None
+
 
 def _config_from_env_and_yaml() -> PyWorkflowConfig:
     """

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/context/base.py

@@ -133,6 +133,9 @@ class WorkflowContext(ABC):
         """
         self._run_id = run_id
         self._workflow_name = workflow_name
+        self._tracing: dict[str, Any] | None = None
+        self._tracing_provider: Any = None  # TracingProvider instance
+        self._trace_id: str | None = None  # Stable trace ID
 
     @property
     def run_id(self) -> str:
@@ -144,6 +147,20 @@ class WorkflowContext(ABC):
         """Get the current workflow name."""
         return self._workflow_name
 
+    @property
+    def tracing(self) -> dict[str, Any] | None:
+        """Get the tracing provider config (e.g. Langfuse credentials), or None."""
+        return self._tracing
+
+    @tracing.setter
+    def tracing(self, value: dict[str, Any] | None) -> None:
+        self._tracing = value
+
+    @property
+    def tracing_provider(self) -> Any:
+        """Get the active TracingProvider instance, or None."""
+        return self._tracing_provider
+
     # =========================================================================
     # Abstract methods - must be implemented by subclasses
     # =========================================================================

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/core/registry.py

@@ -23,6 +23,9 @@ class WorkflowMetadata:
     tags: list[str] | None = None
     description: str | None = None  # Docstring from the workflow function
     context_class: type | None = None  # StepContext subclass for step context access
+    tracing: dict[str, Any] | None = (
+        None  # Optional tracing provider config (e.g. Langfuse credentials)
+    )
 
     def __post_init__(self) -> None:
         if self.tags is None:
@@ -44,6 +47,9 @@ class StepMetadata:
     timeout: int | None = None
     metadata: dict[str, Any] | None = None
     force_local: bool = False
+    is_generator: bool = (
+        False  # If True, creates a Langfuse generation span instead of a regular span
+    )
 
     def __post_init__(self) -> None:
         if self.metadata is None:
@@ -73,6 +79,7 @@ class WorkflowRegistry:
         max_duration: str | None = None,
         tags: list[str] | None = None,
         context_class: type | None = None,
+        tracing: dict[str, Any] | None = None,
     ) -> None:
         """
         Register a workflow.
@@ -84,6 +91,7 @@ class WorkflowRegistry:
             max_duration: Optional maximum duration
             tags: Optional list of tags (max 3)
             context_class: Optional StepContext subclass for step context access
+            tracing: Optional tracing provider config dict (e.g. Langfuse credentials)
         """
         if name in self._workflows:
             existing = self._workflows[name]
@@ -101,6 +109,7 @@ class WorkflowRegistry:
             max_duration=max_duration,
             tags=tags or [],
             context_class=context_class,
+            tracing=tracing,
         )
 
         self._workflows[name] = workflow_meta
@@ -160,6 +169,7 @@ class WorkflowRegistry:
         timeout: int | None = None,
         metadata: dict[str, Any] | None = None,
         force_local: bool = False,
+        is_generator: bool = False,
     ) -> None:
         """
         Register a step.
@@ -173,6 +183,7 @@ class WorkflowRegistry:
             timeout: Optional timeout in seconds
             metadata: Optional metadata dict
             force_local: If True, always execute inline even in distributed runtimes
+            is_generator: If True, creates a Langfuse generation span instead of a regular span
         """
         if name in self._steps:
             existing = self._steps[name]
@@ -190,6 +201,7 @@ class WorkflowRegistry:
             timeout=timeout,
             metadata=metadata or {},
             force_local=force_local,
+            is_generator=is_generator,
         )
 
         self._steps[name] = step_meta
@@ -259,9 +271,12 @@ def register_workflow(
     max_duration: str | None = None,
     tags: list[str] | None = None,
     context_class: type | None = None,
+    tracing: dict[str, Any] | None = None,
 ) -> None:
     """Register a workflow in the global registry."""
-    _registry.register_workflow(name, func, original_func, max_duration, tags, context_class)
+    _registry.register_workflow(
+        name, func, original_func, max_duration, tags, context_class, tracing
+    )
 
 
 def get_workflow(name: str) -> WorkflowMetadata | None:
@@ -293,10 +308,19 @@ def register_step(
     timeout: int | None = None,
     metadata: dict[str, Any] | None = None,
     force_local: bool = False,
+    is_generator: bool = False,
 ) -> None:
     """Register a step in the global registry."""
     _registry.register_step(
-        name, func, original_func, max_retries, retry_delay, timeout, metadata, force_local
+        name,
+        func,
+        original_func,
+        max_retries,
+        retry_delay,
+        timeout,
+        metadata,
+        force_local,
+        is_generator,
     )
 
 

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/core/step.py

@@ -58,6 +58,7 @@ def step(
     timeout: int | None = None,
     metadata: dict[str, Any] | None = None,
     force_local: bool = False,
+    is_generator: bool = False,
 ) -> Callable:
     """
     Decorator to mark functions as workflow steps.
@@ -77,6 +78,8 @@ def step(
         force_local: If True, always execute inline even in distributed
             runtimes (e.g., Celery). Useful for lightweight steps where
             the overhead of message broker dispatch is undesirable.
+        is_generator: If True, creates a Langfuse generation span instead of
+            a regular span. Use for LLM/AI steps that produce generated content.
 
     Returns:
         Decorated step function
@@ -209,6 +212,7 @@ def step(
                     max_retries=max_retries,
                     retry_delay=retry_delay,
                     timeout=timeout,
+                    is_generator=is_generator,
                 )
 
             # Check if we're resuming from a retry
@@ -297,6 +301,9 @@ def step(
                     step_id=step_id,
                 )
 
+                # Record tracing span for locally executed step
+                _record_step_tracing(ctx, step_name, step_id, is_generator, result, args, kwargs)
+
                 return result
 
             except SuspensionSignal:
@@ -458,6 +465,7 @@ def step(
             timeout=timeout,
             metadata=metadata,
             force_local=force_local,
+            is_generator=is_generator,
         )
 
         # Store metadata on wrapper
@@ -468,6 +476,7 @@ def step(
         wrapper.__step_timeout__ = timeout  # type: ignore[attr-defined]
         wrapper.__step_metadata__ = metadata or {}  # type: ignore[attr-defined]
         wrapper.__step_force_local__ = force_local  # type: ignore[attr-defined]
+        wrapper.__step_is_generator__ = is_generator  # type: ignore[attr-defined]
 
         return wrapper
 
@@ -627,6 +636,7 @@ async def _dispatch_step_to_celery(
     max_retries: int,
     retry_delay: str | int | list[int],
     timeout: int | None,
+    is_generator: bool = False,
 ) -> Any:
     """
     Dispatch step execution to Celery step worker.
@@ -736,6 +746,8 @@ async def _dispatch_step_to_celery(
         context_data=context_data,
         context_class_name=context_class_name,
         workflow_name=ctx.workflow_name,
+        tracing=ctx.tracing,
+        is_generator=is_generator,
     )
 
     logger.info(
@@ -753,3 +765,38 @@ async def _dispatch_step_to_celery(
         step_name=step_name,
         task_id=task_result.id,
     )
+
+
+def _record_step_tracing(
+    ctx: Any,
+    step_name: str,
+    step_id: str,
+    is_generator: bool,
+    result: Any,
+    step_args: tuple = (),
+    step_kwargs: dict | None = None,
+) -> None:
+    """Record a tracing span for a completed step. No-op if tracing is not configured."""
+    tp = getattr(ctx, "_tracing_provider", None)
+    if not tp:
+        return
+    try:
+        trace_id = getattr(ctx, "_trace_id", None)
+        if not trace_id:
+            return
+
+        step_input = dict(step_kwargs) if step_kwargs else {}
+        if step_args:
+            step_input["_args"] = [str(a)[:500] for a in step_args]
+
+        tp.record_step_span(
+            trace_id=trace_id,
+            step_name=step_name,
+            step_id=step_id,
+            is_generator=is_generator,
+            result=result,
+            step_input=step_input or None,
+            trace_name=ctx.workflow_name,
+        )
+    except Exception:
+        pass  # Never fail the workflow because of tracing

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/core/workflow.py

@@ -9,7 +9,9 @@ decorated with @workflow to enable:
 - Fault tolerance
 """
 
+import contextlib
 import functools
+import hashlib
 from collections.abc import Callable
 from typing import Any
 
@@ -34,6 +36,7 @@ def workflow(
     recover_on_worker_loss: bool | None = None,
     max_recovery_attempts: int | None = None,
     context_class: type | None = None,
+    tracing: dict[str, Any] | None = None,
 ) -> Callable:
     """
     Decorator to mark async functions as workflows.
@@ -53,6 +56,9 @@ def workflow(
         context_class: Optional StepContext subclass for step context access.
             When provided, enables get_step_context() and set_step_context()
             for passing context data to steps running on remote workers.
+        tracing: Optional tracing provider config dict. When provided, enables
+            observability tracing (e.g. Langfuse) for the workflow and its steps.
+            Example: {"provider": "langfuse", "public_key": "...", "secret_key": "...", "host": "..."}
 
     Returns:
         Decorated workflow function
@@ -127,6 +133,7 @@ def workflow(
             max_duration=max_duration,
             tags=validated_tags,
             context_class=context_class,
+            tracing=tracing,
         )
 
         # Store metadata on wrapper
@@ -142,6 +149,7 @@ def workflow(
             max_recovery_attempts  # None = use config default
         )
         wrapper.__workflow_context_class__ = context_class  # type: ignore[attr-defined]
+        wrapper.__workflow_tracing__ = tracing  # type: ignore[attr-defined]
 
         return wrapper
 
@@ -161,6 +169,7 @@ async def execute_workflow_with_context(
     runtime: str | None = None,
     storage_config: dict | None = None,
     parent_run_id: str | None = None,
+    tracing: dict | None = None,
 ) -> Any:
     """
     Execute workflow function with proper context setup.
@@ -210,6 +219,31 @@ async def execute_workflow_with_context(
     ctx._storage_config = storage_config
     ctx._parent_run_id = parent_run_id
 
+    # Tracing config resolution order:
+    # 1. pyworkflow.start(tracing={...}) — runtime creds (e.g. from FlowHunt)
+    # 2. @workflow(tracing={...}) — decorator-level config
+    # 3. configure(TRACING_CONFIG={...}) — global config
+    ctx.tracing = tracing or getattr(
+        workflow_func, "__workflow_tracing__", None
+    )  # 1. start(tracing=) or 2. @workflow(tracing=)
+
+    # Initialize tracing provider
+    tracing_provider = None
+    from pyworkflow.tracing import create_tracing_provider
+
+    if ctx.tracing:
+        tracing_provider = create_tracing_provider(ctx.tracing)  # source 1 or 2
+    if not tracing_provider:
+        from pyworkflow.config import get_config
+
+        _global_tracing = get_config().TRACING_CONFIG
+        tracing_provider = create_tracing_provider(_global_tracing)  # source 3
+        if tracing_provider:
+            ctx.tracing = _global_tracing  # propagate to Celery workers
+    if tracing_provider:
+        ctx._trace_id = hashlib.md5(run_id.encode()).hexdigest()
+    ctx._tracing_provider = tracing_provider
+
     # Set cancellation state if requested before execution
     if cancellation_requested:
         ctx.request_cancellation(reason="Cancellation requested before execution")
@@ -243,6 +277,7 @@ async def execute_workflow_with_context(
     try:
         # Note: Event replay is handled by LocalContext in its constructor
         # when event_log is provided
+        result = None  # For tracing in finally block
 
         logger.info(
             f"Executing workflow: {workflow_name}",
@@ -276,6 +311,7 @@ async def execute_workflow_with_context(
 
     except SuspensionSignal as e:
         # Workflow suspended (sleep/hook) - only happens in durable mode
+        # Don't end tracing - will continue on resume
         logger.info(
             f"Workflow suspended: {e.reason}",
             run_id=run_id,
@@ -341,6 +377,45 @@ async def execute_workflow_with_context(
         raise
 
     finally:
+        # Flush tracing data — wrapped in broad try/except to never crash the workflow
+        if tracing_provider:
+            try:
+                _trace_input = None
+                _trace_output = None
+                try:
+                    if args and isinstance(args[0], dict):
+                        _trace_input = args[0].get("input_value")
+                    if result is not None and isinstance(result, dict):
+                        _out = result.get("outputs", result)
+                        if isinstance(_out, dict):
+                            for v in _out.values():
+                                if isinstance(v, dict) and v.get("text_output"):
+                                    _trace_output = v["text_output"]
+                                    break
+                        if not _trace_output:
+                            _trace_output = result.get("text_output")
+                except Exception:
+                    pass
+                with contextlib.suppress(Exception):
+                    await tracing_provider.shutdown()
+                try:
+                    if ctx._trace_id:
+                        trace_params = (ctx.tracing or {}).get("trace_params", {})
+                        meta = trace_params.get("metadata") or {}
+                        meta["run_id"] = run_id
+                        trace_params["metadata"] = meta
+                        await tracing_provider.update_trace(
+                            trace_id=ctx._trace_id,
+                            name=workflow_name,
+                            input=_trace_input,
+                            output=_trace_output,
+                            trace_params=trace_params,
+                        )
+                except Exception as e:
+                    logger.error(f"TRACING: update_trace_via_api failed: {e}")
+            except Exception as e:
+                logger.error(f"TRACING: unexpected error in tracing finally block: {e}")
+
         # Clear step context if it was set
         if step_context_token is not None:
             from pyworkflow.context.step_context import _reset_step_context

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/engine/executor.py

@@ -47,6 +47,7 @@ async def start(
     durable: bool | None = None,
     storage: StorageBackend | None = None,
     idempotency_key: str | None = None,
+    tracing: dict | None = None,
     **kwargs: Any,
 ) -> str:
     """
@@ -62,6 +63,8 @@ async def start(
         durable: Whether workflow is durable (None = use workflow/config default)
         storage: Storage backend instance (None = use configured storage)
         idempotency_key: Optional key for idempotent execution
+        tracing: Optional tracing provider config dict (e.g. Langfuse credentials).
+            Overrides the @workflow decorator's tracing parameter if provided.
         **kwargs: Keyword arguments for workflow
 
     Returns:
@@ -168,6 +171,7 @@ async def start(
         idempotency_key=idempotency_key,
         max_duration=workflow_meta.max_duration,
         metadata={},  # Run-level metadata
+        tracing=tracing,
     )
 
 

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/runtime/base.py

@@ -37,6 +37,7 @@ class Runtime(ABC):
         idempotency_key: str | None = None,
         max_duration: str | None = None,
         metadata: dict | None = None,
+        tracing: dict | None = None,
     ) -> str:
         """
         Start a new workflow execution.

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/runtime/celery.py

@@ -116,6 +116,7 @@ class CeleryRuntime(Runtime):
         idempotency_key: str | None = None,
         max_duration: str | None = None,
         metadata: dict | None = None,
+        tracing: dict | None = None,
     ) -> str:
         """
         Start a workflow execution by dispatching to Celery workers.
@@ -152,6 +153,7 @@ class CeleryRuntime(Runtime):
             run_id=run_id,
             storage_config=storage_config,
             idempotency_key=idempotency_key,
+            tracing=tracing,
         )
 
         logger.info(

{pyworkflow_engine-0.2.14 → pyworkflow_engine-0.3.0}/pyworkflow/runtime/local.py

@@ -134,6 +134,7 @@ class LocalRuntime(Runtime):
         idempotency_key: str | None = None,
         max_duration: str | None = None,
         metadata: dict | None = None,
+        tracing: dict | None = None,
     ) -> str:
         """Start a workflow execution in the current process."""
         from pyworkflow.core.workflow import execute_workflow_with_context
@@ -190,6 +191,7 @@ class LocalRuntime(Runtime):
                 args=args,
                 kwargs=kwargs,
                 durable=durable,
+                tracing=tracing,
             )
 
             if durable and storage is not None:

pyworkflow_engine-0.3.0/pyworkflow/tracing/__init__.py

@@ -0,0 +1,17 @@
+"""
+Tracing module for PyWorkflow.
+
+Provides observability tracing (e.g. Langfuse) for workflows and steps.
+"""
+
+from pyworkflow.tracing.base import BaseTracingProvider
+from pyworkflow.tracing.factory import create_tracing_provider
+from pyworkflow.tracing.types import LLMCallData, ToolCallData, TracingStepResult
+
+__all__ = [
+    "BaseTracingProvider",
+    "create_tracing_provider",
+    "LLMCallData",
+    "ToolCallData",
+    "TracingStepResult",
+]