agnt5 0.2.2__cp39-abi3-macosx_11_0_arm64.whl → 0.2.4__cp39-abi3-macosx_11_0_arm64.whl

agnt5/workflow.py

@@ -5,26 +5,438 @@ from __future__ import annotations
 import asyncio
 import functools
 import inspect
+import logging
 import uuid
 from typing import Any, Callable, Dict, Optional, TypeVar, cast
 
+from ._schema_utils import extract_function_metadata, extract_function_schemas
 from .context import Context
+from .entity import Entity, EntityState, _get_state_manager
+from .function import FunctionContext
 from .types import HandlerFunc, WorkflowConfig
-from .function import _extract_function_schemas, _extract_function_metadata
+from ._telemetry import setup_module_logger
+
+logger = setup_module_logger(__name__)
 
 T = TypeVar("T")
 
 # Global workflow registry
 _WORKFLOW_REGISTRY: Dict[str, WorkflowConfig] = {}
 
+class WorkflowContext(Context):
+    """
+    Context for durable workflows.
+
+    Extends base Context with:
+    - State management via WorkflowEntity.state
+    - Step tracking and replay
+    - Orchestration (task, parallel, gather)
+    - Checkpointing (step)
+
+    WorkflowContext delegates state to the underlying WorkflowEntity,
+    which provides durability and state change tracking for AI workflows.
+    """
+
+    def __init__(
+        self,
+        workflow_entity: "WorkflowEntity",  # Forward reference
+        run_id: str,
+        attempt: int = 0,
+        runtime_context: Optional[Any] = None,
+    ) -> None:
+        """
+        Initialize workflow context.
+
+        Args:
+            workflow_entity: WorkflowEntity instance managing workflow state
+            run_id: Unique workflow run identifier
+            attempt: Retry attempt number (0-indexed)
+            runtime_context: RuntimeContext for trace correlation
+        """
+        super().__init__(run_id, attempt, runtime_context)
+        self._workflow_entity = workflow_entity
+        self._step_counter: int = 0  # Track step sequence
+
+    # === State Management ===
+
+    @property
+    def state(self):
+        """
+        Delegate to WorkflowEntity.state for durable state management.
+
+        Returns:
+            WorkflowState instance from the workflow entity
+
+        Example:
+            ctx.state.set("status", "processing")
+            status = ctx.state.get("status")
+        """
+        return self._workflow_entity.state
+
+    # === Orchestration ===
+
+    async def task(
+        self,
+        handler: Union[str, Callable],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Execute a function and wait for result.
+
+        Supports two calling patterns:
+
+        1. **Type-safe with function reference (recommended)**:
+           ```python
+           result = await ctx.task(process_data, arg1, arg2, kwarg=value)
+           ```
+           Full IDE support, type checking, and refactoring safety.
+
+        2. **Legacy string-based (backward compatible)**:
+           ```python
+           result = await ctx.task("function_name", input=data)
+           ```
+           String lookup without type safety.
+
+        Args:
+            handler: Either a @function reference (recommended) or string name (legacy)
+            *args: Positional arguments to pass to the function
+            **kwargs: Keyword arguments to pass to the function
+
+        Returns:
+            Function result
+
+        Example (type-safe):
+            ```python
+            @function
+            async def process_data(ctx: FunctionContext, data: list, multiplier: int = 2):
+                return [x * multiplier for x in data]
+
+            @workflow
+            async def my_workflow(ctx: WorkflowContext):
+                # Type-safe call with positional and keyword args
+                result = await ctx.task(process_data, [1, 2, 3], multiplier=3)
+                return result
+            ```
+
+        Example (legacy):
+            ```python
+            result = await ctx.task("process_data", input={"data": [1, 2, 3]})
+            ```
+        """
+        from .function import FunctionRegistry
+
+        # Extract handler name from function reference or use string
+        if callable(handler):
+            handler_name = handler.__name__
+            if not hasattr(handler, '_agnt5_config'):
+                raise ValueError(
+                    f"Function '{handler_name}' is not a registered @function. "
+                    f"Did you forget to add the @function decorator?"
+                )
+        else:
+            handler_name = handler
+
+        # Generate unique step name for durability
+        step_name = f"{handler_name}_{self._step_counter}"
+        self._step_counter += 1
+
+        # Check if step already completed (for replay)
+        if self._workflow_entity.has_completed_step(step_name):
+            result = self._workflow_entity.get_completed_step(step_name)
+            self._logger.info(f"🔄 Replaying cached step: {step_name}")
+            return result
+
+        # Execute function
+        self._logger.info(f"▶️  Executing new step: {step_name}")
+        func_config = FunctionRegistry.get(handler_name)
+        if func_config is None:
+            raise ValueError(f"Function '{handler_name}' not found in registry")
+
+        # Create FunctionContext for the function execution
+        func_ctx = FunctionContext(
+            run_id=f"{self.run_id}:task:{handler_name}",
+            runtime_context=self._runtime_context,
+        )
+
+        # Execute function with arguments
+        # Support legacy pattern: ctx.task("func_name", input=data) or ctx.task(func_ref, input=data)
+        if len(args) == 0 and "input" in kwargs:
+            # Legacy pattern - single input parameter
+            input_data = kwargs.pop("input")  # Remove from kwargs
+            result = await func_config.handler(func_ctx, input_data, **kwargs)
+        else:
+            # Type-safe pattern - pass all args/kwargs
+            result = await func_config.handler(func_ctx, *args, **kwargs)
+
+        # Record step completion in WorkflowEntity
+        self._workflow_entity.record_step_completion(step_name, handler_name, args or kwargs, result)
+
+        return result
+
+    async def parallel(self, *tasks: Awaitable[T]) -> List[T]:
+        """
+        Run multiple tasks in parallel.
+
+        Args:
+            *tasks: Async tasks to run in parallel
+
+        Returns:
+            List of results in the same order as tasks
+
+        Example:
+            result1, result2 = await ctx.parallel(
+                fetch_data(source1),
+                fetch_data(source2)
+            )
+        """
+        import asyncio
+        return list(await asyncio.gather(*tasks))
+
+    async def gather(self, **tasks: Awaitable[T]) -> Dict[str, T]:
+        """
+        Run tasks in parallel with named results.
+
+        Args:
+            **tasks: Named async tasks to run in parallel
+
+        Returns:
+            Dictionary mapping names to results
+
+        Example:
+            results = await ctx.gather(
+                db=query_database(),
+                api=fetch_api()
+            )
+        """
+        import asyncio
+        keys = list(tasks.keys())
+        values = list(tasks.values())
+        results = await asyncio.gather(*values)
+        return dict(zip(keys, results))
+
+    async def step(
+        self,
+        name: str,
+        func_or_awaitable: Union[Callable[[], Awaitable[T]], Awaitable[T]]
+    ) -> T:
+        """
+        Checkpoint expensive operations for durability.
+
+        If workflow crashes, won't re-execute this step on retry.
+
+        Args:
+            name: Unique name for this checkpoint
+            func_or_awaitable: Either an async function or awaitable
+
+        Returns:
+            The result of the function/awaitable
+
+        Example:
+            result = await ctx.step("load", load_data())
+        """
+        import inspect
+
+        # Check if step already completed (for replay)
+        if self._workflow_entity.has_completed_step(name):
+            result = self._workflow_entity.get_completed_step(name)
+            self._logger.info(f"🔄 Replaying checkpoint: {name}")
+            return result
+
+        # Execute and checkpoint
+        if inspect.iscoroutine(func_or_awaitable) or inspect.isawaitable(func_or_awaitable):
+            result = await func_or_awaitable
+        else:
+            result = await func_or_awaitable()
+
+        # Record step completion
+        self._workflow_entity.record_step_completion(name, "checkpoint", None, result)
+
+        return result
+
+
+# ============================================================================
+# WorkflowEntity: Entity specialized for workflow execution state
+# ============================================================================
+
+class WorkflowEntity(Entity):
+    """
+    Entity specialized for workflow execution state.
+
+    Extends Entity with workflow-specific capabilities:
+    - Step tracking for replay and crash recovery
+    - State change tracking for debugging and audit (AI workflows)
+    - Completed step cache for efficient replay
+
+    Workflows are temporary entities - they exist for the duration of
+    execution and their state is used for coordination between steps.
+    """
+
+    def __init__(self, run_id: str):
+        """
+        Initialize workflow entity.
+
+        Args:
+            run_id: Unique workflow run identifier
+        """
+        # Initialize as entity with workflow key pattern
+        super().__init__(key=f"workflow:{run_id}")
+
+        # Step tracking for replay and recovery
+        self._step_events: list[Dict[str, Any]] = []
+        self._completed_steps: Dict[str, Any] = {}
+
+        # State change tracking for debugging/audit (AI workflows)
+        self._state_changes: list[Dict[str, Any]] = []
+
+        logger.debug(f"Created WorkflowEntity: {run_id}")
+
+    @property
+    def run_id(self) -> str:
+        """Extract run_id from workflow key."""
+        return self._key.split(":", 1)[1]
+
+    def record_step_completion(
+        self,
+        step_name: str,
+        handler_name: str,
+        input_data: Any,
+        result: Any
+    ) -> None:
+        """
+        Record completed step for replay and recovery.
+
+        Args:
+            step_name: Unique step identifier
+            handler_name: Function handler name
+            input_data: Input data passed to function
+            result: Function result
+        """
+        self._step_events.append({
+            "step_name": step_name,
+            "handler_name": handler_name,
+            "input": input_data,
+            "result": result
+        })
+        self._completed_steps[step_name] = result
+        logger.debug(f"Recorded step completion: {step_name}")
+
+    def get_completed_step(self, step_name: str) -> Optional[Any]:
+        """
+        Get result of completed step (for replay).
+
+        Args:
+            step_name: Step identifier
+
+        Returns:
+            Step result if completed, None otherwise
+        """
+        return self._completed_steps.get(step_name)
+
+    def has_completed_step(self, step_name: str) -> bool:
+        """Check if step has been completed."""
+        return step_name in self._completed_steps
+
+    @property
+    def state(self) -> "WorkflowState":
+        """
+        Get workflow state with change tracking.
+
+        Returns WorkflowState which tracks all state mutations
+        for debugging and replay of AI workflows.
+        """
+        if self._state is None:
+            # Get state dict from state manager
+            state_manager = _get_state_manager()
+            state_dict = state_manager.get_or_create_state(self._state_key)
+            self._state = WorkflowState(state_dict, self)
+        return self._state
+
+
+class WorkflowState(EntityState):
+    """
+    State interface for WorkflowEntity with change tracking.
+
+    Extends EntityState to track all state mutations for:
+    - AI workflow debugging
+    - Audit trail
+    - Replay capabilities
+    """
+
+    def __init__(self, state_dict: Dict[str, Any], workflow_entity: WorkflowEntity):
+        """
+        Initialize workflow state.
+
+        Args:
+            state_dict: Dictionary to use for state storage
+            workflow_entity: Parent workflow entity for tracking
+        """
+        super().__init__(state_dict)
+        self._workflow_entity = workflow_entity
+
+    def set(self, key: str, value: Any) -> None:
+        """Set value and track change."""
+        super().set(key, value)
+        # Track change for debugging/audit
+        import time
+        self._workflow_entity._state_changes.append({
+            "key": key,
+            "value": value,
+            "timestamp": time.time(),
+            "deleted": False
+        })
+
+    def delete(self, key: str) -> None:
+        """Delete key and track change."""
+        super().delete(key)
+        # Track deletion
+        import time
+        self._workflow_entity._state_changes.append({
+            "key": key,
+            "value": None,
+            "timestamp": time.time(),
+            "deleted": True
+        })
+
+    def clear(self) -> None:
+        """Clear all state and track change."""
+        super().clear()
+        # Track clear operation
+        import time
+        self._workflow_entity._state_changes.append({
+            "key": "__clear__",
+            "value": None,
+            "timestamp": time.time(),
+            "deleted": True
+        })
+
 
 class WorkflowRegistry:
     """Registry for workflow handlers."""
 
     @staticmethod
     def register(config: WorkflowConfig) -> None:
-        """Register a workflow handler."""
+        """
+        Register a workflow handler.
+
+        Raises:
+            ValueError: If a workflow with this name is already registered
+        """
+        if config.name in _WORKFLOW_REGISTRY:
+            existing_workflow = _WORKFLOW_REGISTRY[config.name]
+            logger.error(
+                f"Workflow name collision detected: '{config.name}'\n"
+                f"  First defined in:  {existing_workflow.handler.__module__}\n"
+                f"  Also defined in:   {config.handler.__module__}\n"
+                f"  This is a bug - workflows must have unique names."
+            )
+            raise ValueError(
+                f"Workflow '{config.name}' is already registered. "
+                f"Use @workflow(name='unique_name') to specify a different name."
+            )
+
         _WORKFLOW_REGISTRY[config.name] = config
+        logger.debug(f"Registered workflow '{config.name}'")
 
     @staticmethod
     def get(name: str) -> Optional[WorkflowConfig]:
@@ -55,25 +467,30 @@ def workflow(
     """
     Decorator to mark a function as an AGNT5 durable workflow.
 
-    Phase 1: In-memory orchestration with asyncio primitives.
-    Phase 2: Durable execution with checkpoint/replay and distributed tasks.
+    Workflows use WorkflowEntity for state management and WorkflowContext
+    for orchestration. State changes are automatically tracked for replay.
 
     Args:
         name: Custom workflow name (default: function's __name__)
 
     Example:
         @workflow
-        async def process_order(ctx: Context, order_id: str) -> dict:
+        async def process_order(ctx: WorkflowContext, order_id: str) -> dict:
+            # Durable state - survives crashes
+            ctx.state.set("status", "processing")
+            ctx.state.set("order_id", order_id)
+
             # Validate order
-            order = await ctx.task("orders", "validate", input={"order_id": order_id})
+            order = await ctx.task(validate_order, input={"order_id": order_id})
 
-            # Process payment
-            payment = await ctx.task("payments", "charge", input={"amount": order["total"]})
+            # Process payment (checkpointed - won't re-execute on crash)
+            payment = await ctx.step("payment", process_payment(order["total"]))
 
             # Fulfill order
-            await ctx.task("fulfillment", "ship", input={"order_id": order_id})
+            await ctx.task(ship_order, input={"order_id": order_id})
 
-            return {"status": "completed"}
+            ctx.state.set("status", "completed")
+            return {"status": ctx.state.get("status")}
     """
 
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
@@ -86,7 +503,7 @@ def workflow(
 
         if not params or params[0].name != "ctx":
             raise ValueError(
-                f"Workflow '{workflow_name}' must have 'ctx: Context' as first parameter"
+                f"Workflow '{workflow_name}' must have 'ctx: WorkflowContext' as first parameter"
             )
 
         # Convert sync to async if needed
@@ -101,10 +518,10 @@ def workflow(
             handler_func = cast(HandlerFunc, async_wrapper)
 
         # Extract schemas from type hints
-        input_schema, output_schema = _extract_function_schemas(func)
+        input_schema, output_schema = extract_function_schemas(func)
 
         # Extract metadata (description, etc.)
-        metadata = _extract_function_metadata(func)
+        metadata = extract_function_metadata(func)
 
         # Register workflow
         config = WorkflowConfig(
@@ -119,17 +536,24 @@ def workflow(
         # Create wrapper that provides context
         @functools.wraps(func)
         async def wrapper(*args: Any, **kwargs: Any) -> Any:
-            # Create context if not provided
-            if not args or not isinstance(args[0], Context):
-                # Auto-create context for direct workflow calls
-                ctx = Context(
-                    run_id=f"workflow-{uuid.uuid4().hex[:8]}",
-                    component_type="workflow",
+            # Create WorkflowEntity and WorkflowContext if not provided
+            if not args or not isinstance(args[0], WorkflowContext):
+                # Auto-create workflow entity and context for direct workflow calls
+                run_id = f"workflow-{uuid.uuid4().hex[:8]}"
+
+                # Create WorkflowEntity to manage state
+                workflow_entity = WorkflowEntity(run_id=run_id)
+
+                # Create WorkflowContext that wraps the entity
+                ctx = WorkflowContext(
+                    workflow_entity=workflow_entity,
+                    run_id=run_id,
                 )
+
                 # Execute workflow
                 return await handler_func(ctx, *args, **kwargs)
             else:
-                # Context provided - use it
+                # WorkflowContext provided - use it
                 return await handler_func(*args, **kwargs)
 
         # Store config on wrapper for introspection

{agnt5-0.2.2.dist-info → agnt5-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agnt5
-Version: 0.2.2
+Version: 0.2.4
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -16,6 +16,7 @@ Requires-Dist: maturin>=1.9.3
 Requires-Dist: docstring-parser>=0.15
 Requires-Dist: typing-extensions>=4.8
 Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.0
 Summary: AGNT5 Python SDK - Build durable, resilient agent-first applications
 Author-email: AGNT5 Team <team@agnt5.com>
 License: Apache-2.0

agnt5-0.2.4.dist-info/RECORD

@@ -0,0 +1,22 @@
+agnt5-0.2.4.dist-info/METADATA,sha256=0WFxoXI9jA26vzUKQp2Oqj8ZCb7H50v9PR7pxpXNXgo,994
+agnt5-0.2.4.dist-info/WHEEL,sha256=vpqC0tRn_8bTHidvtrPbrnFQPZnrhuKzsjDdeKwCd58,102
+agnt5/__init__.py,sha256=NAziyM0ZKahdzqAP2edFHTbVHYVdIjEGXm0oEHdmiuo,2011
+agnt5/_compat.py,sha256=BGuy3v5VDOHVa5f3Z-C22iMN19lAt0mPmXwF3qSSWxI,369
+agnt5/_core.abi3.so,sha256=_eS8cS8moUInKso8deBYKQBY56Mwt2gOUw3xCkvzMBs,11889296
+agnt5/_retry_utils.py,sha256=loHsWY5BR4wZy57IzcDEjQAy88DHVwVIr25Cn1d9GPA,5801
+agnt5/_schema_utils.py,sha256=MR67RW757T4Oq2Jqf4kB61H_b51zwaf3CLWELnkngRo,9572
+agnt5/_telemetry.py,sha256=bIY9AvBRjJBTHoBPbfR6X1OgaiUf-T0vCoi0_snsWXA,5957
+agnt5/agent.py,sha256=VQqNSd9o3tezxEo6jpWQyk399Wue7NgCpZvuQ-LtiTI,27494
+agnt5/client.py,sha256=kXksazgxdVXWaG9OkjJA4cWruNtcS-ENhtnkrIdw-Nk,23212
+agnt5/context.py,sha256=S2OzPkhn_jnqSWfT21mSYOux8vHaLKQxcAvggZDHQek,2378
+agnt5/entity.py,sha256=dhdxXUxED79u3OlX9yw-2TLCC9VqBcJqES2kx-fDChs,19041
+agnt5/exceptions.py,sha256=mZ0q-NK6OKhYxgwBJpIbgpgzk-CJaFIHDbp1EE-pS7I,925
+agnt5/function.py,sha256=f1vaAlJRwuo8cxCOGEd8XPido00mOhlPS8UJJx-6hJI,11041
+agnt5/lm.py,sha256=AQ8xz5u1mywBKIGwT3AJKtChVdxo5HOCvzdwZ4Ilbb0,21177
+agnt5/tool.py,sha256=uc4L-Q9QyLzQDe-MZKk2Wo3o5e-mK8tfaQwVDgQdouQ,13133
+agnt5/tracing.py,sha256=Mh2-OfnQM61lM_P8gxJstafdsUA8Gxoo1lP-Joxhub8,5980
+agnt5/types.py,sha256=Zb71ZMwvrt1p4SH18cAKunp2y5tao_W5_jGYaPDejQo,2840
+agnt5/version.py,sha256=rOq1mObLihnnKgKqBrwZA0zwOPudEKVFcW1a48ynkqc,573
+agnt5/worker.py,sha256=_BnqqqvQE16FuezFbPda9FoiKAwcezSaxxNjU0rTjhs,33576
+agnt5/workflow.py,sha256=sve85o4N16PrlIwtQOqJPsHHWgl388SV702IPEXO7A8,18528
+agnt5-0.2.4.dist-info/RECORD,,

agnt5-0.2.2.dist-info/RECORD

@@ -1,19 +0,0 @@
-agnt5-0.2.2.dist-info/METADATA,sha256=lGJESH9_HBx_FmDngvJl_cDBCF02SfJsL_mJlWusN1E,965
-agnt5-0.2.2.dist-info/WHEEL,sha256=vpqC0tRn_8bTHidvtrPbrnFQPZnrhuKzsjDdeKwCd58,102
-agnt5/__init__.py,sha256=dQ83SuDrAU83leQ38mDVdthZFP0SWJMK67xq1d4uGtg,1933
-agnt5/_compat.py,sha256=BGuy3v5VDOHVa5f3Z-C22iMN19lAt0mPmXwF3qSSWxI,369
-agnt5/_core.abi3.so,sha256=cWTAlgAIyMzQ4Gmp-Cq-5lnlZ1BTYg4IEWhgxv3WvjA,11895200
-agnt5/_telemetry.py,sha256=ZeABlTMoEnXYnBFVOn6ruaSvfeS7r_czI_Pk_tiCfhY,4899
-agnt5/agent.py,sha256=sU0qSZyXl_D6YrQKxtlyR6gggPJ0zZKC63bWtJvMzJI,26557
-agnt5/client.py,sha256=Zesl-TIie8Gwq-ajTauPlAsF7jZm5TPk307iHdxQ2SM,21214
-agnt5/context.py,sha256=fF_eL_rY-GFnGFpL6wqPERykluGf2obpD-mYrGpsUTc,23817
-agnt5/entity.py,sha256=kLMBlHSQJeRqNwfWcXeLcM5UF9JcU8aET6TQBh6tSBA,43966
-agnt5/exceptions.py,sha256=mZ0q-NK6OKhYxgwBJpIbgpgzk-CJaFIHDbp1EE-pS7I,925
-agnt5/function.py,sha256=hH7rH9c_ZohUuNoLlBJHuiR5qPhw0L0pkrVVrpL_g2M,11273
-agnt5/lm.py,sha256=VvKVm_7VneBggLoCZEXfTavpPJJXNpbARrgHPCqhrX8,18915
-agnt5/tool.py,sha256=5s0YK5-BFIlQNUJOQHbejQsWW17r43rAC4zRvJnh9qg,12513
-agnt5/types.py,sha256=Zb71ZMwvrt1p4SH18cAKunp2y5tao_W5_jGYaPDejQo,2840
-agnt5/version.py,sha256=rOq1mObLihnnKgKqBrwZA0zwOPudEKVFcW1a48ynkqc,573
-agnt5/worker.py,sha256=n4zL4DUocRlcpitsOPbrZ4frz-E_ZoVgIhKH_76iq00,31502
-agnt5/workflow.py,sha256=1sFAvtdZn6n7nDDb0YyE6LGJGuN2KVFNVo9Q42N_7_k,4529
-agnt5-0.2.2.dist-info/RECORD,,