feat: support native catch exception node in agentspec adapter

Author: paul-cayet

docs/wayflowcore/source/core/changelog.rst

@@ -62,6 +62,12 @@ New features
 Improvements
 ^^^^^^^^^^^^
 
+* **Support for native Agent Spec CatchExceptionNode:**
+
+  WayFlow flows using the CatchExceptionStep now convert to the native Agent Spec
+  CatchExceptionNode when compatible (i.e., when catching all exceptions).
+
+
 * **Support list, dict and tuple output types in MCP tools:**
 
   MCP tools now support non-string output types (list of string, dictionary of strings

wayflowcore/src/wayflowcore/datastore/inmemory.py

@@ -5,12 +5,10 @@
 # (UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.
 
 from logging import getLogger
-from typing import Any, Dict, List, Optional, Union, cast, overload
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union, cast, overload
 from warnings import warn
 
-import numpy as np
-import pandas as pd
-
+from wayflowcore._utils.lazy_loader import LazyLoader
 from wayflowcore.component import Component
 from wayflowcore.datastore._datatable import Datatable
 from wayflowcore.datastore._utils import (
@@ -24,6 +22,16 @@
 from wayflowcore.serialization.context import DeserializationContext, SerializationContext
 from wayflowcore.serialization.serializer import SerializableObject, serialize_to_dict
 
+if TYPE_CHECKING:
+    # Important: do not move these imports out of the TYPE_CHECKING
+    # Otherwise, importing the module when they are not installed would lead to an import error.
+    import numpy as np
+    import pandas as pd
+else:
+    np = LazyLoader("numpy")
+    pd = LazyLoader("pandas")
+
+
 logger = getLogger(__name__)
 
 _INMEMORY_USER_WARNING = "InMemoryDatastore is for DEVELOPMENT and PROOF-OF-CONCEPT ONLY!"

wayflowcore/src/wayflowcore/serialization/_builtins_deserialization_plugin.py

@@ -33,6 +33,9 @@
 from pyagentspec.flows.nodes.agentnode import AgentNode as AgentSpecAgentNode
 from pyagentspec.flows.nodes.apinode import ApiNode as AgentSpecApiNode
 from pyagentspec.flows.nodes.branchingnode import BranchingNode as AgentSpecBranchingNode
+from pyagentspec.flows.nodes.catchexceptionnode import (
+    CatchExceptionNode as AgentSpecCatchExceptionNode,
+)
 from pyagentspec.flows.nodes.endnode import EndNode as AgentSpecEndNode
 from pyagentspec.flows.nodes.flownode import FlowNode as AgentSpecFlowNode
 from pyagentspec.flows.nodes.llmnode import LlmNode as AgentSpecLlmNode
@@ -115,7 +118,9 @@
 from wayflowcore.agentspec.components import (
     PluginVllmEmbeddingConfig as AgentSpecPluginVllmEmbeddingConfig,
 )
-from wayflowcore.agentspec.components import all_deserialization_plugin
+from wayflowcore.agentspec.components import (
+    all_deserialization_plugin,
+)
 from wayflowcore.agentspec.components.agent import ExtendedAgent as AgentSpecExtendedAgent
 from wayflowcore.agentspec.components.contextprovider import (
     PluginConstantContextProvider as AgentSpecPluginConstantContextProvider,
@@ -359,6 +364,7 @@
 from wayflowcore.outputparser import PythonToolOutputParser as RuntimePythonToolOutputParser
 from wayflowcore.outputparser import RegexOutputParser as RuntimeRegexOutputParser
 from wayflowcore.outputparser import RegexPattern as RuntimeRegexPattern
+from wayflowcore.property import AnyProperty as RuntimeAnyProperty
 from wayflowcore.property import JsonSchemaParam
 from wayflowcore.property import ListProperty as RuntimeListProperty
 from wayflowcore.property import Property as RuntimeProperty
@@ -997,10 +1003,18 @@ def _find_property(properties: List[AgentSpecProperty], name: str) -> AgentSpecP
                 conversion_context.convert(edge, tool_registry, converted_components)
                 for edge in data_flow_connections or []
             ]
-            control_flow_edges: List[RuntimeControlFlowEdge] = [
-                conversion_context.convert(edge, tool_registry, converted_components)
-                for edge in agentspec_component.control_flow_connections
-            ]
+            control_flow_edges: List[RuntimeControlFlowEdge] = []
+            for edge in agentspec_component.control_flow_connections:
+                if (
+                    isinstance(edge.from_node, AgentSpecCatchExceptionNode)
+                    and edge.from_branch == AgentSpecCatchExceptionNode.CAUGHT_EXCEPTION_BRANCH
+                ):
+                    # we need to rename the branch used in the CatchExceptionNode
+                    edge.from_branch = RuntimeCatchExceptionStep.DEFAULT_EXCEPTION_BRANCH
+                control_flow_edges.append(
+                    conversion_context.convert(edge, tool_registry, converted_components)
+                )
+
             for step in steps.values():
                 for branch in step.get_branches():
                     edge_exists = any(
@@ -1359,6 +1373,55 @@ def _find_property(properties: List[AgentSpecProperty], name: str) -> AgentSpecP
                 except_on=agentspec_component.except_on,
                 **self._get_rt_nodes_arguments(agentspec_component, metadata_info),
             )
+        elif isinstance(agentspec_component, AgentSpecCatchExceptionNode):
+            # Standard CatchExceptionNode from Agent Spec does not expose catch_all_exceptions
+            # and except_on fields
+            # Also, the output of the catch exception node might be renamed,
+            # so we have to use output mapping when needed
+            rt_nodes_arguments = self._get_node_arguments(agentspec_component, metadata_info)
+            if agentspec_component.outputs:
+                subflow_outputs_titles = {
+                    p.title for p in agentspec_component.subflow.outputs or []
+                }
+                caught_exception_property = next(
+                    (
+                        p
+                        for p in agentspec_component.outputs
+                        if p.title not in subflow_outputs_titles
+                    ),
+                    None,
+                )
+                if caught_exception_property is None:
+                    raise ValueError(
+                        f"Internal error: Agent Spec CatchExceptionNode '{agentspec_component.name}' "
+                        "is missing a output for the exception info. Make sure the pyagentspec "
+                        "component is successfully validated."
+                    )
+                if (
+                    caught_exception_property.title
+                    != RuntimeCatchExceptionStep.EXCEPTION_PAYLOAD_OUTPUT_NAME
+                ):
+                    # there is no output mapping by default. We add one to handle renaming
+                    rt_nodes_arguments["output_mapping"] = {
+                        RuntimeCatchExceptionStep.EXCEPTION_PAYLOAD_OUTPUT_NAME: caught_exception_property.title
+                    }
+
+                # we need to add a default output property for the exception name
+                rt_nodes_arguments["output_descriptors"].append(
+                    RuntimeAnyProperty(
+                        name=RuntimeCatchExceptionStep.EXCEPTION_NAME_OUTPUT_NAME,
+                        default_value="",
+                    )
+                )
+
+            return RuntimeCatchExceptionStep(
+                flow=conversion_context.convert(
+                    agentspec_component.subflow, tool_registry, converted_components
+                ),
+                catch_all_exceptions=True,
+                except_on=None,
+                **rt_nodes_arguments,
+            )
         elif isinstance(agentspec_component, AgentSpecPluginRegexNode):
             regex_pattern = self._regex_pattern_to_runtime(agentspec_component.regex_pattern)
             if not (