agent-framework-declarative 1.0.0__py3-none-any.whl

agent_framework_declarative/_workflows/_executors_control_flow.py

@@ -0,0 +1,461 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Control flow executors for the graph-based declarative workflow system.
+
+Control flow in the graph-based system is handled differently than the interpreter:
+- If/ConditionGroup: Condition evaluation happens in a dedicated evaluator executor that
+  returns a ConditionResult with the first-matching branch index. Edge conditions
+  then check the branch_index to route to the correct branch. This ensures only
+  one branch executes (first-match semantics), matching the interpreter behavior.
+- Foreach: Loop iteration state managed in State + loop edges
+- Goto: Edge to target action (handled by builder)
+- Break/Continue: Special signals for loop control
+
+The key insight is that control flow becomes GRAPH STRUCTURE, not executor logic.
+"""
+
+from typing import Any, cast
+
+from agent_framework import (
+    Message,
+    WorkflowContext,
+    handler,
+)
+
+from ._declarative_base import (
+    ActionComplete,
+    ActionTrigger,
+    ConditionResult,
+    DeclarativeActionExecutor,
+    LoopControl,
+    LoopIterationResult,
+)
+
+# Keys for loop state in State
+LOOP_STATE_KEY = "_declarative_loop_state"
+
+# Index value indicating the else/default branch
+ELSE_BRANCH_INDEX = -1
+
+
+class ConditionGroupEvaluatorExecutor(DeclarativeActionExecutor):
+    """Evaluates conditions for ConditionGroup and outputs the first-matching branch.
+
+    This executor implements first-match semantics by evaluating conditions sequentially
+    and outputting a ConditionResult with the index of the first matching branch.
+    Edge conditions downstream check this index to route to the correct branch.
+
+    This mirrors .NET's ConditionGroupExecutor.ExecuteAsync which returns the step ID
+    of the first matching condition.
+    """
+
+    def __init__(
+        self,
+        action_def: dict[str, Any],
+        conditions: list[dict[str, Any]],
+        *,
+        id: str | None = None,
+    ):
+        """Initialize the condition evaluator.
+
+        Args:
+            action_def: The ConditionGroup action definition
+            conditions: List of condition items, each with 'condition' and optional 'id'
+            id: Optional executor ID
+        """
+        super().__init__(action_def, id=id)
+        self._conditions = conditions
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ConditionResult],
+    ) -> None:
+        """Evaluate conditions and output the first matching branch index."""
+        state = await self._ensure_state_initialized(ctx, trigger)
+
+        # Evaluate conditions sequentially - first match wins
+        for index, cond_item in enumerate(self._conditions):
+            condition_expr = cond_item.get("condition")
+            if condition_expr is None:
+                continue
+
+            # Normalize boolean conditions
+            if condition_expr is True:
+                condition_expr = "=true"
+            elif condition_expr is False:
+                condition_expr = "=false"
+            elif isinstance(condition_expr, str) and not condition_expr.startswith("="):
+                condition_expr = f"={condition_expr}"
+
+            result = state.eval(condition_expr)
+            if bool(result):
+                # First matching condition found
+                await ctx.send_message(ConditionResult(matched=True, branch_index=index, value=result))
+                return
+
+        # No condition matched - use else/default branch
+        await ctx.send_message(ConditionResult(matched=False, branch_index=ELSE_BRANCH_INDEX))
+
+
+class IfConditionEvaluatorExecutor(DeclarativeActionExecutor):
+    """Evaluates a single If condition and outputs a ConditionResult.
+
+    This is simpler than ConditionGroupEvaluator - just evaluates one condition
+    and outputs branch_index=0 (then) or branch_index=-1 (else).
+    """
+
+    def __init__(
+        self,
+        action_def: dict[str, Any],
+        condition_expr: str,
+        *,
+        id: str | None = None,
+    ):
+        """Initialize the if condition evaluator.
+
+        Args:
+            action_def: The If action definition
+            condition_expr: The condition expression to evaluate
+            id: Optional executor ID
+        """
+        super().__init__(action_def, id=id)
+        self._condition_expr = condition_expr
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ConditionResult],
+    ) -> None:
+        """Evaluate the condition and output the result."""
+        state = await self._ensure_state_initialized(ctx, trigger)
+
+        result = state.eval(self._condition_expr)
+        is_truthy = bool(result)
+
+        if is_truthy:
+            await ctx.send_message(ConditionResult(matched=True, branch_index=0, value=result))
+        else:
+            await ctx.send_message(ConditionResult(matched=False, branch_index=ELSE_BRANCH_INDEX, value=result))
+
+
+class ForeachInitExecutor(DeclarativeActionExecutor):
+    """Initializes a foreach loop.
+
+    Sets up the loop state in State and determines if there are items.
+    """
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[LoopIterationResult],
+    ) -> None:
+        """Initialize the loop and check for first item."""
+        state = await self._ensure_state_initialized(ctx, trigger)
+
+        items_expr = self._action_def.get("source")
+        items_raw: Any = state.eval_if_expression(items_expr) or []
+
+        items: list[Any]
+        items = (list(items_raw) if items_raw else []) if not isinstance(items_raw, (list, tuple)) else list(items_raw)  # type: ignore
+
+        loop_id = self.id
+
+        # Store loop state
+        state_data = state.get_state_data()
+        loop_states: dict[str, Any] = cast(dict[str, Any], state_data).setdefault(LOOP_STATE_KEY, {})
+        loop_states[loop_id] = {
+            "items": items,
+            "index": 0,
+            "length": len(items),
+        }
+        state.set_state_data(state_data)
+
+        if items:
+            # Bind the current item and (when requested) the index under the Local scope.
+            item_var = f"Local.{self._action_def.get('itemName', 'item')}"
+            index_var = (
+                f"Local.{self._action_def.get('indexName', 'index')}" if "indexName" in self._action_def else None
+            )
+
+            state.set(item_var, items[0])
+            if index_var:
+                state.set(index_var, 0)
+
+            await ctx.send_message(LoopIterationResult(has_next=True, current_item=items[0], current_index=0))
+        else:
+            await ctx.send_message(LoopIterationResult(has_next=False))
+
+
+class ForeachNextExecutor(DeclarativeActionExecutor):
+    """Advances to the next item in a foreach loop.
+
+    This executor is triggered after the loop body completes.
+    """
+
+    def __init__(
+        self,
+        action_def: dict[str, Any],
+        init_executor_id: str,
+        *,
+        id: str | None = None,
+    ):
+        """Initialize with reference to the init executor.
+
+        Args:
+            action_def: The Foreach action definition
+            init_executor_id: ID of the corresponding ForeachInitExecutor
+            id: Optional executor ID
+        """
+        super().__init__(action_def, id=id)
+        self._init_executor_id = init_executor_id
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[LoopIterationResult],
+    ) -> None:
+        """Advance to next item and send result."""
+        state = await self._ensure_state_initialized(ctx, trigger)
+
+        loop_id = self._init_executor_id
+
+        # Get loop state
+        state_data = state.get_state_data()
+        loop_states: dict[str, Any] = cast(dict[str, Any], state_data).get(LOOP_STATE_KEY, {})
+        loop_state = loop_states.get(loop_id)
+
+        if not loop_state:
+            # No loop state - shouldn't happen but handle gracefully
+            await ctx.send_message(LoopIterationResult(has_next=False))
+            return
+
+        items = loop_state["items"]
+        current_index = loop_state["index"] + 1
+
+        if current_index < len(items):
+            # Update loop state
+            loop_state["index"] = current_index
+            state.set_state_data(state_data)
+
+            # Rebind the current item and (when requested) the index under the Local scope.
+            item_var = f"Local.{self._action_def.get('itemName', 'item')}"
+            index_var = (
+                f"Local.{self._action_def.get('indexName', 'index')}" if "indexName" in self._action_def else None
+            )
+
+            state.set(item_var, items[current_index])
+            if index_var:
+                state.set(index_var, current_index)
+
+            await ctx.send_message(
+                LoopIterationResult(has_next=True, current_item=items[current_index], current_index=current_index)
+            )
+        else:
+            # Loop complete - clean up
+            loop_states_dict = cast(dict[str, Any], state_data).get(LOOP_STATE_KEY, {})
+            if loop_id in loop_states_dict:
+                del loop_states_dict[loop_id]
+            state.set_state_data(state_data)
+
+            await ctx.send_message(LoopIterationResult(has_next=False))
+
+    @handler
+    async def handle_loop_control(
+        self,
+        control: LoopControl,
+        ctx: WorkflowContext[LoopIterationResult],
+    ) -> None:
+        """Handle break/continue signals."""
+        state = self._get_state(ctx.state)
+
+        if control.action == "break":
+            # Clean up loop state and signal done
+            state_data = state.get_state_data()
+            loop_states: dict[str, Any] = cast(dict[str, Any], state_data).get(LOOP_STATE_KEY, {})
+            if self._init_executor_id in loop_states:
+                del loop_states[self._init_executor_id]
+                state.set_state_data(state_data)
+
+            await ctx.send_message(LoopIterationResult(has_next=False))
+
+        elif control.action == "continue":
+            # Just advance to next iteration
+            await self.handle_action(ActionTrigger(), ctx)
+
+
+class BreakLoopExecutor(DeclarativeActionExecutor):
+    """Executor for BreakLoop action.
+
+    Sends a LoopControl signal to break out of the enclosing loop.
+    """
+
+    def __init__(
+        self,
+        action_def: dict[str, Any],
+        loop_next_executor_id: str,
+        *,
+        id: str | None = None,
+    ):
+        """Initialize with reference to the loop's next executor.
+
+        Args:
+            action_def: The action definition
+            loop_next_executor_id: ID of the ForeachNextExecutor to signal
+            id: Optional executor ID
+        """
+        super().__init__(action_def, id=id)
+        self._loop_next_executor_id = loop_next_executor_id
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[LoopControl],
+    ) -> None:
+        """Send break signal to the loop."""
+        await ctx.send_message(LoopControl(action="break"))
+
+
+class ContinueLoopExecutor(DeclarativeActionExecutor):
+    """Executor for ContinueLoop action.
+
+    Sends a LoopControl signal to continue to next iteration.
+    """
+
+    def __init__(
+        self,
+        action_def: dict[str, Any],
+        loop_next_executor_id: str,
+        *,
+        id: str | None = None,
+    ):
+        """Initialize with reference to the loop's next executor.
+
+        Args:
+            action_def: The action definition
+            loop_next_executor_id: ID of the ForeachNextExecutor to signal
+            id: Optional executor ID
+        """
+        super().__init__(action_def, id=id)
+        self._loop_next_executor_id = loop_next_executor_id
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[LoopControl],
+    ) -> None:
+        """Send continue signal to the loop."""
+        await ctx.send_message(LoopControl(action="continue"))
+
+
+class EndWorkflowExecutor(DeclarativeActionExecutor):
+    """Executor for EndWorkflow/EndDialog action.
+
+    This executor simply doesn't send any message, causing the workflow
+    to terminate at this point.
+    """
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """End the workflow by not sending any continuation message."""
+        # Don't send ActionComplete - workflow ends here
+        pass
+
+
+class EndConversationExecutor(DeclarativeActionExecutor):
+    """Executor for EndConversation action."""
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """End the conversation."""
+        # For now, just don't continue
+        # In a full implementation, this would signal to close the conversation
+        pass
+
+
+# Passthrough executor for joining control flow branches
+class JoinExecutor(DeclarativeActionExecutor):
+    """Executor that joins multiple branches back together.
+
+    Used after If/ConditionGroup to merge control flow back to a single path.
+    Also used as passthrough nodes for else/default branches.
+    """
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: dict[str, Any]
+        | str
+        | list[Message]
+        | ActionTrigger
+        | ActionComplete
+        | ConditionResult
+        | LoopIterationResult,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Simply pass through to continue the workflow."""
+        await self._ensure_state_initialized(ctx, trigger)
+        await ctx.send_message(ActionComplete())
+
+
+class CancelDialogExecutor(DeclarativeActionExecutor):
+    """Executor for CancelDialog action.
+
+    Cancels the current dialog/workflow, equivalent to .NET CancelDialog.
+    This terminates execution similarly to EndWorkflow.
+    """
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Cancel the current dialog/workflow."""
+        # CancelDialog terminates execution without continuing
+        # Similar to EndWorkflow but semantically different (cancellation vs completion)
+        pass
+
+
+class CancelAllDialogsExecutor(DeclarativeActionExecutor):
+    """Executor for CancelAllDialogs action.
+
+    Cancels all dialogs in the execution stack, equivalent to .NET CancelAllDialogs.
+    This terminates the entire workflow execution.
+    """
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Cancel all dialogs/workflows."""
+        # CancelAllDialogs terminates all execution
+        pass
+
+
+# Mapping of control flow action kinds to executor classes
+# Note: Most control flow is handled by the builder creating graph structure,
+# these are the executors that are part of that structure
+CONTROL_FLOW_EXECUTORS: dict[str, type[DeclarativeActionExecutor]] = {
+    "EndWorkflow": EndWorkflowExecutor,
+    "EndDialog": EndWorkflowExecutor,
+    "EndConversation": EndConversationExecutor,
+    "CancelDialog": CancelDialogExecutor,
+    "CancelAllDialogs": CancelAllDialogsExecutor,
+}

agent_framework_declarative/_workflows/_executors_external_input.py

@@ -0,0 +1,243 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""External input executors for declarative workflows.
+
+These executors handle interactions that require external input (user questions
+and external integrations), using the request_info pattern to pause the workflow
+and wait for responses.
+"""
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, cast
+
+from agent_framework import (
+    WorkflowContext,
+    handler,
+    response_handler,
+)
+
+from ._declarative_base import (
+    ActionComplete,
+    DeclarativeActionExecutor,
+)
+
+
+def _get_prompt_text(action_def: dict[str, Any], primary_key: str, fallback_key: str) -> Any:
+    """Return the prompt text from an action definition.
+
+    Accepts a nested ``{primary_key: {"text": ...}}`` mapping, a bare
+    string under ``primary_key``, or a top-level ``fallback_key`` value.
+    """
+    match action_def.get(primary_key):
+        case {"text": text}:
+            return text
+        case str() as text:
+            return text
+        case _:
+            return action_def.get(fallback_key, "")
+
+
+def _get_output_path(action_def: dict[str, Any], default: str) -> str:
+    """Return the state path where the action result should be written.
+
+    Looks at ``variable``, then ``output.property``, then top-level
+    ``property``, falling back to ``default``.
+    """
+    output = action_def.get("output")
+    nested = cast(dict[str, Any], output).get("property") if isinstance(output, dict) else None
+    return action_def.get("variable") or nested or action_def.get("property") or default
+
+
+@dataclass
+class ExternalInputRequest:
+    """Request for external input (triggers workflow pause).
+
+    Aligns with .NET ExternalInputRequest pattern. Used by Question and
+    RequestExternalInput executors to signal that user input is needed.
+    The workflow will pause via request_info and wait for an ExternalInputResponse.
+
+    Attributes:
+        request_id: Unique identifier for this request.
+        message: The prompt or question to display to the user.
+        request_type: A free-form discriminator describing the kind of input
+            being requested. ``QuestionExecutor`` emits ``"question"`` and
+            ``RequestExternalInputExecutor`` defaults to ``"external"``; callers
+            may supply any other string via the ``requestType`` field on a
+            ``RequestExternalInput`` action (e.g. ``"approval"``) and it is
+            propagated unchanged.
+        metadata: Additional context (choices, output_property, timeout, etc.).
+    """
+
+    request_id: str
+    message: str
+    request_type: str = "external"
+    metadata: dict[str, Any] = field(default_factory=dict)  # type: ignore
+
+
+@dataclass
+class ExternalInputResponse:
+    """Response to an ExternalInputRequest.
+
+    Provided by the caller to resume workflow execution with user input.
+
+    Attributes:
+        user_input: The user's text response.
+        value: Optional typed value (e.g., bool for confirmations, selected choice).
+    """
+
+    user_input: str
+    value: Any = None
+
+
+class QuestionExecutor(DeclarativeActionExecutor):
+    """Executor that asks the user a question and waits for a response.
+
+    Uses the request_info pattern to pause execution until the user provides an answer.
+    The response is stored in workflow state at the configured output property.
+    """
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Ask the question and wait for a response."""
+        state = await self._ensure_state_initialized(ctx, trigger)
+
+        question_text = _get_prompt_text(self._action_def, primary_key="question", fallback_key="text")
+        output_property = _get_output_path(self._action_def, default="Local.answer")
+        default_value = self._action_def.get("default", self._action_def.get("defaultValue"))
+        choices = self._action_def.get("choices", [])
+        allow_free_text = self._action_def.get("allowFreeText", True)
+
+        evaluated_question = state.eval_if_expression(question_text)
+
+        # Build choices metadata
+        choices_data: list[dict[str, str]] | None = None
+        if choices:
+            choices_data = []
+            for c in choices:
+                if isinstance(c, dict):
+                    c_dict: dict[str, Any] = dict(c)  # type: ignore[arg-type]
+                    choices_data.append({
+                        "value": c_dict.get("value", ""),
+                        "label": c_dict.get("label") or c_dict.get("value", ""),
+                    })
+                else:
+                    choices_data.append({"value": str(c), "label": str(c)})
+
+        # Store output property in shared state for response handler
+        ctx.state.set("_question_output_property", output_property)
+        ctx.state.set("_question_default_value", default_value)
+
+        # Request external input - workflow pauses here
+        await ctx.request_info(
+            ExternalInputRequest(
+                request_id=str(uuid.uuid4()),
+                message=str(evaluated_question),
+                request_type="question",
+                metadata={
+                    "output_property": output_property,
+                    "choices": choices_data,
+                    "allow_free_text": allow_free_text,
+                    "default_value": default_value,
+                },
+            ),
+            ExternalInputResponse,
+        )
+
+    @response_handler
+    async def handle_response(
+        self,
+        original_request: ExternalInputRequest,
+        response: ExternalInputResponse,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Handle the user's response to the question."""
+        state = self._get_state(ctx.state)
+
+        output_property = original_request.metadata.get("output_property", "Local.answer")
+        answer = response.value if response.value is not None else response.user_input
+
+        if output_property:
+            state.set(output_property, answer)
+
+        await ctx.send_message(ActionComplete())
+
+
+class RequestExternalInputExecutor(DeclarativeActionExecutor):
+    """Executor that requests external input/approval.
+
+    Used for complex external integrations beyond simple questions,
+    such as approval workflows, document uploads, or external system integrations.
+    """
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Request external input."""
+        state = await self._ensure_state_initialized(ctx, trigger)
+
+        message = _get_prompt_text(self._action_def, primary_key="prompt", fallback_key="message")
+        output_property = _get_output_path(self._action_def, default="Local.externalInput")
+        default_value = self._action_def.get("default")
+
+        request_type = self._action_def.get("requestType", "external")
+        timeout_seconds = self._action_def.get("timeout")
+        required_fields = self._action_def.get("requiredFields", [])
+        metadata = self._action_def.get("metadata", {})
+
+        evaluated_message = state.eval_if_expression(message)
+
+        # Build request metadata
+        request_metadata: dict[str, Any] = {
+            **metadata,
+            "output_property": output_property,
+            "required_fields": required_fields,
+            "default_value": default_value,
+        }
+
+        if timeout_seconds:
+            request_metadata["timeout_seconds"] = timeout_seconds
+
+        # Request external input - workflow pauses here
+        await ctx.request_info(
+            ExternalInputRequest(
+                request_id=str(uuid.uuid4()),
+                message=str(evaluated_message),
+                request_type=request_type,
+                metadata=request_metadata,
+            ),
+            ExternalInputResponse,
+        )
+
+    @response_handler
+    async def handle_response(
+        self,
+        original_request: ExternalInputRequest,
+        response: ExternalInputResponse,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Handle the external input response."""
+        state = self._get_state(ctx.state)
+
+        output_property = original_request.metadata.get("output_property", "Local.externalInput")
+
+        # Store the response value or user_input
+        result = response.value if response.value is not None else response.user_input
+        if output_property:
+            state.set(output_property, result)
+
+        await ctx.send_message(ActionComplete())
+
+
+# Mapping of external input action kinds to executor classes
+EXTERNAL_INPUT_EXECUTORS: dict[str, type[DeclarativeActionExecutor]] = {
+    "Question": QuestionExecutor,
+    "RequestExternalInput": RequestExternalInputExecutor,
+}