arcade-core 2.2.2__py3-none-any.whl → 2.4.0__py3-none-any.whl

arcade_core/auth.py

@@ -51,6 +51,15 @@ class Atlassian(OAuth2):
         super().__init__(id=id, scopes=scopes)
 
 
+class ClickUp(OAuth2):
+    """Marks a tool as requiring ClickUp authorization."""
+
+    provider_id: str = "clickup"
+
+    def __init__(self, *, id: Optional[str] = None, scopes: Optional[list[str]] = None):  # noqa: A002
+        super().__init__(id=id, scopes=scopes)
+
+
 class Discord(OAuth2):
     """Marks a tool as requiring Discord authorization."""
 

arcade_core/catalog.py

@@ -27,7 +27,12 @@ from pydantic_core import PydanticUndefined
 
 from arcade_core.annotations import Inferrable
 from arcade_core.auth import OAuth2, ToolAuthorization
-from arcade_core.errors import ToolDefinitionError
+from arcade_core.errors import (
+    ToolDefinitionError,
+    ToolInputSchemaError,
+    ToolkitLoadError,
+    ToolOutputSchemaError,
+)
 from arcade_core.schema import (
     TOOL_NAME_SEPARATOR,
     FullyQualifiedName,
@@ -224,7 +229,9 @@ class ToolCatalog(BaseModel):
         fully_qualified_name = definition.get_fully_qualified_name()
 
         if fully_qualified_name in self._tools:
-            raise KeyError(f"Tool '{definition.name}' already exists in the catalog.")
+            raise ToolkitLoadError(
+                f"Tool '{definition.name}' in toolkit '{toolkit_name}' already exists in the catalog."
+            )
 
         if str(fully_qualified_name).lower() in self._disabled_tools:
             logger.info(f"Tool '{fully_qualified_name!s}' is disabled and will not be cataloged.")
@@ -270,20 +277,26 @@ class ToolCatalog(BaseModel):
                     tool_func = getattr(module, tool_name)
                     self.add_tool(tool_func, toolkit, module)
 
+                except ToolDefinitionError as e:
+                    raise e.with_context(tool_name) from e
+                except ToolkitLoadError as e:
+                    raise e.with_context(toolkit.name) from e
+                except ImportError as e:
+                    raise ToolkitLoadError(
+                        f"Could not import module {module_name}. Reason: {e}"
+                    ).with_context(tool_name)
                 except AttributeError as e:
                     raise ToolDefinitionError(
                         f"Could not import tool {tool_name} in module {module_name}. Reason: {e}"
-                    )
-                except ImportError as e:
-                    raise ToolDefinitionError(f"Could not import module {module_name}. Reason: {e}")
+                    ).with_context(tool_name)
                 except TypeError as e:
                     raise ToolDefinitionError(
                         f"Type error encountered while adding tool {tool_name} from {module_name}. Reason: {e}"
-                    )
+                    ).with_context(tool_name)
                 except Exception as e:
                     raise ToolDefinitionError(
                         f"Error encountered while adding tool {tool_name} from {module_name}. Reason: {e}"
-                    )
+                    ).with_context(tool_name)
 
     def __getitem__(self, name: FullyQualifiedName) -> MaterializedTool:
         return self.get_tool(name)
@@ -392,11 +405,11 @@ class ToolCatalog(BaseModel):
         # Hard requirement: tools must have descriptions
         tool_description = getattr(tool, "__tool_description__", None)
         if not tool_description:
-            raise ToolDefinitionError(f"Tool {raw_tool_name} is missing a description")
+            raise ToolDefinitionError(f"Tool '{raw_tool_name}' is missing a description")
 
         # If the function returns a value, it must have a type annotation
         if does_function_return_value(tool) and tool.__annotations__.get("return") is None:
-            raise ToolDefinitionError(f"Tool {raw_tool_name} must have a return type annotation")
+            raise ToolOutputSchemaError(f"Tool '{raw_tool_name}' must have a return type")
 
         auth_requirement = create_auth_requirement(tool)
         secrets_requirement = create_secrets_requirement(tool)
@@ -438,7 +451,7 @@ def create_input_definition(func: Callable) -> ToolInput:
     for _, param in inspect.signature(func, follow_wrapped=True).parameters.items():
         if param.annotation is ToolContext:
             if tool_context_param_name is not None:
-                raise ToolDefinitionError(
+                raise ToolInputSchemaError(
                     f"Only one ToolContext parameter is supported, but tool {func.__name__} has multiple."
                 )
 
@@ -483,7 +496,11 @@ def create_output_definition(func: Callable) -> ToolOutput:
         )
 
     if hasattr(return_type, "__metadata__"):
-        description = return_type.__metadata__[0] if return_type.__metadata__ else None  # type: ignore[assignment]
+        description = (
+            return_type.__metadata__[0]
+            if return_type.__metadata__
+            else "No description provided for return type."
+        )
         return_type = return_type.__origin__
 
     # Unwrap Optional types
@@ -631,7 +648,7 @@ def extract_field_info(param: inspect.Parameter) -> ToolParamInfo:
     """
     annotation = param.annotation
     if annotation == inspect.Parameter.empty:
-        raise ToolDefinitionError(f"Parameter {param} has no type annotation.")
+        raise ToolInputSchemaError(f"Parameter {param} has no type annotation.")
 
     # Get the majority of the param info from either the Pydantic Field() or regular inspection
     if isinstance(param.default, FieldInfo):
@@ -650,7 +667,7 @@ def extract_field_info(param: inspect.Parameter) -> ToolParamInfo:
     elif len(str_annotations) == 2:
         new_name = str_annotations[0]
         if not new_name.isidentifier():
-            raise ToolDefinitionError(
+            raise ToolInputSchemaError(
                 f"Invalid parameter name: '{new_name}' is not a valid identifier. "
                 "Identifiers must start with a letter or underscore, "
                 "and can only contain letters, digits, or underscores."
@@ -658,7 +675,7 @@ def extract_field_info(param: inspect.Parameter) -> ToolParamInfo:
         param_info.name = new_name
         param_info.description = str_annotations[1]
     else:
-        raise ToolDefinitionError(
+        raise ToolInputSchemaError(
             f"Parameter {param} has too many string annotations. Expected 0, 1, or 2, got {len(str_annotations)}."
         )
 
@@ -673,10 +690,10 @@ def extract_field_info(param: inspect.Parameter) -> ToolParamInfo:
 
     # Final reality check
     if param_info.description is None:
-        raise ToolDefinitionError(f"Parameter {param_info.name} is missing a description")
+        raise ToolInputSchemaError(f"Parameter '{param_info.name}' is missing a description")
 
     if wire_type_info.wire_type is None:
-        raise ToolDefinitionError(f"Unknown parameter type: {param_info.field_type}")
+        raise ToolInputSchemaError(f"Unknown parameter type: {param_info.field_type}")
 
     return ToolParamInfo.from_param_info(param_info, wire_type_info, is_inferrable)
 
@@ -792,6 +809,7 @@ def extract_properties(type_to_check: type) -> dict[str, WireTypeInfo] | None:
                 field_type = next(arg for arg in get_args(field_type) if arg is not type(None))
 
             # Get wire type info recursively
+            # field_type cannot be None here due to the check above
             wire_info = get_wire_type_info(field_type)
             properties[field_name] = wire_info
 
@@ -870,7 +888,7 @@ def extract_python_param_info(param: inspect.Parameter) -> ParamInfo:
     # Union types are not currently supported
     # (other than optional, which is handled above)
     if is_union(field_type):
-        raise ToolDefinitionError(
+        raise ToolInputSchemaError(
             f"Parameter {param.name} is a union type. Only optional types are supported."
         )
 
@@ -890,7 +908,7 @@ def extract_pydantic_param_info(param: inspect.Parameter) -> ParamInfo:
         if callable(param.default.default_factory):
             default_value = param.default.default_factory()
         else:
-            raise ToolDefinitionError(f"Default factory for parameter {param} is not callable.")
+            raise ToolInputSchemaError(f"Default factory for parameter {param} is not callable.")
 
     # If the param is Annotated[], unwrap the annotation to get the "real" type
     # Otherwise, use the literal type
@@ -973,7 +991,9 @@ def create_func_models(func: Callable) -> tuple[type[BaseModel], type[BaseModel]
         tool_field_info = extract_field_info(param)
         param_fields = {
             "default": tool_field_info.default,
-            "description": tool_field_info.description,
+            "description": tool_field_info.description
+            if tool_field_info.description
+            else "No description provided.",
             # TODO more here?
         }
         input_fields[name] = (tool_field_info.field_type, Field(**param_fields))
@@ -981,7 +1001,6 @@ def create_func_models(func: Callable) -> tuple[type[BaseModel], type[BaseModel]
     input_model = create_model(f"{snake_to_pascal_case(func.__name__)}Input", **input_fields)  # type: ignore[call-overload]
 
     output_model = determine_output_model(func)
-
     return input_model, output_model
 
 
@@ -991,8 +1010,14 @@ def determine_output_model(func: Callable) -> type[BaseModel]:  # noqa: C901
     """
     return_annotation = inspect.signature(func).return_annotation
     output_model_name = f"{snake_to_pascal_case(func.__name__)}Output"
+
+    # If the return annotation is empty, create a model with no fields
     if return_annotation is inspect.Signature.empty:
         return create_model(output_model_name)
+
+    # If the return annotation has an __origin__ attribute
+    # and does not have a __metadata__ attribute.
+    # This is the case for TypedDicts.
     elif hasattr(return_annotation, "__origin__"):
         if hasattr(return_annotation, "__metadata__"):
             field_type = return_annotation.__args__[0]
@@ -1008,15 +1033,30 @@ def determine_output_model(func: Callable) -> type[BaseModel]:  # noqa: C901
                 )
                 return create_model(
                     output_model_name,
-                    result=(typeddict_model, Field(description=str(description))),
+                    result=(
+                        typeddict_model,
+                        Field(
+                            description=str(description)
+                            if description
+                            else "No description provided."
+                        ),
+                    ),
                 )
 
+            # If the return annotation has a description, use it
             if description:
-                return create_model(
-                    output_model_name,
-                    result=(field_type, Field(description=str(description))),
-                )
-        # Handle Union types
+                try:
+                    return create_model(
+                        output_model_name,
+                        result=(field_type, Field(description=str(description))),
+                    )
+                except Exception:
+                    raise ToolOutputSchemaError(
+                        f"Unsupported output type '{field_type}'. Only built-in Python types, TypedDicts, "
+                        "Pydantic models, and standard collections are supported as tool output types."
+                    )
+
+        # If the return annotation is a Union type
         origin = return_annotation.__origin__
         if origin is typing.Union:
             # For union types, create a model with the first non-None argument
@@ -1037,10 +1077,15 @@ def determine_output_model(func: Callable) -> type[BaseModel]:  # noqa: C901
                         )
                     return create_model(
                         output_model_name,
-                        result=(arg, Field(description="No description provided.")),
+                        result=(
+                            arg,
+                            Field(description="No description provided."),
+                        ),
                     )
-        # when the return_annotation has an __origin__ attribute
+
+        # If the return annotation has an __origin__ attribute
         # and does not have a __metadata__ attribute.
+        # This is the case for TypedDicts.
         return create_model(
             output_model_name,
             result=(
@@ -1049,7 +1094,7 @@ def determine_output_model(func: Callable) -> type[BaseModel]:  # noqa: C901
             ),
         )
     else:
-        # Check if return type is TypedDict
+        # If the return annotation is a TypedDict
         if is_typeddict(return_annotation):
             typeddict_model = create_model_from_typeddict(return_annotation, output_model_name)
             return create_model(
@@ -1060,10 +1105,13 @@ def determine_output_model(func: Callable) -> type[BaseModel]:  # noqa: C901
                 ),
             )
 
-        # Handle simple return types (like str)
+        # If the return annotation is a simple type (like str)
         return create_model(
             output_model_name,
-            result=(return_annotation, Field(description="No description provided.")),
+            result=(
+                return_annotation,
+                Field(description="No description provided."),
+            ),
         )
 
 

arcade_core/errors.py

@@ -1,103 +1,378 @@
 import traceback
-from typing import Optional
-
-
-class ToolkitError(Exception):
+import warnings
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any
+
+
+class ErrorKind(str, Enum):
+    """Error kind that is comprised of
+    - the who (toolkit, tool, upstream)
+    - the when (load time, definition parsing time, runtime)
+    - the what (bad_definition, bad_input, bad_output, retry, context_required, fatal, etc.)"""
+
+    TOOLKIT_LOAD_FAILED = "TOOLKIT_LOAD_FAILED"
+    TOOL_DEFINITION_BAD_DEFINITION = "TOOL_DEFINITION_BAD_DEFINITION"
+    TOOL_DEFINITION_BAD_INPUT_SCHEMA = "TOOL_DEFINITION_BAD_INPUT_SCHEMA"
+    TOOL_DEFINITION_BAD_OUTPUT_SCHEMA = "TOOL_DEFINITION_BAD_OUTPUT_SCHEMA"
+    TOOL_RUNTIME_BAD_INPUT_VALUE = "TOOL_RUNTIME_BAD_INPUT_VALUE"
+    TOOL_RUNTIME_BAD_OUTPUT_VALUE = "TOOL_RUNTIME_BAD_OUTPUT_VALUE"
+    TOOL_RUNTIME_RETRY = "TOOL_RUNTIME_RETRY"
+    TOOL_RUNTIME_CONTEXT_REQUIRED = "TOOL_RUNTIME_CONTEXT_REQUIRED"
+    TOOL_RUNTIME_FATAL = "TOOL_RUNTIME_FATAL"
+    UPSTREAM_RUNTIME_BAD_REQUEST = "UPSTREAM_RUNTIME_BAD_REQUEST"
+    UPSTREAM_RUNTIME_AUTH_ERROR = "UPSTREAM_RUNTIME_AUTH_ERROR"
+    UPSTREAM_RUNTIME_NOT_FOUND = "UPSTREAM_RUNTIME_NOT_FOUND"
+    UPSTREAM_RUNTIME_VALIDATION_ERROR = "UPSTREAM_RUNTIME_VALIDATION_ERROR"
+    UPSTREAM_RUNTIME_RATE_LIMIT = "UPSTREAM_RUNTIME_RATE_LIMIT"
+    UPSTREAM_RUNTIME_SERVER_ERROR = "UPSTREAM_RUNTIME_SERVER_ERROR"
+    UPSTREAM_RUNTIME_UNMAPPED = "UPSTREAM_RUNTIME_UNMAPPED"
+    UNKNOWN = "UNKNOWN"
+
+
+class ToolkitError(Exception, ABC):
     """
-    Base class for all errors related to toolkits.
+    Base class for all Arcade errors.
+
+    Note: This class is an abstract class and cannot be instantiated directly.
+
+    These errors are ultimately converted to the ToolCallError schema.
+    Attributes expected from subclasses:
+      message                   : str                    # user-facing error message
+      kind                      : ErrorKind              # the error kind
+      can_retry                 : bool                   # whether the operation can be retried
+      developer_message         : str | None             # developer-facing error details
+      status_code               : int | None             # HTTP status code when relevant
+      additional_prompt_content : str | None             # content for retry prompts
+      retry_after_ms            : int | None             # milliseconds to wait before retry
+      stacktrace                : str | None             # stacktrace information
+      extra                     : dict[str, Any] | None  # arbitrary structured metadata
     """
 
-    pass
+    def __new__(cls, *args: Any, **kwargs: Any) -> "ToolkitError":
+        abs_methods = getattr(cls, "__abstractmethods__", None)
+        if abs_methods:
+            raise TypeError(f"Can't instantiate abstract class {cls.__name__}")
+        return super().__new__(cls)
+
+    @abstractmethod
+    def create_message_prefix(self, name: str) -> str:
+        pass
+
+    def with_context(self, name: str) -> "ToolkitError":
+        """
+        Add context to the error message.
+
+        Args:
+            name: The name of the tool or toolkit that caused the error.
+
+        Returns:
+            The error with the context added to the message.
+        """
+        prefix = self.create_message_prefix(name)
+        self.message = f"{prefix}{self.message}"  # type: ignore[has-type]
+        if hasattr(self, "developer_message") and self.developer_message:  # type: ignore[has-type]
+            self.developer_message = f"{prefix}{self.developer_message}"  # type: ignore[has-type]
+
+        return self
+
+    @property
+    def is_toolkit_error(self) -> bool:
+        """Check if this error originated from loading a toolkit."""
+        return hasattr(self, "kind") and self.kind.name.startswith("TOOLKIT_")
+
+    @property
+    def is_tool_error(self) -> bool:
+        """Check if this error originated from a tool."""
+        return hasattr(self, "kind") and self.kind.name.startswith("TOOL_")
+
+    @property
+    def is_upstream_error(self) -> bool:
+        """Check if this error originated from an upstream service."""
+        return hasattr(self, "kind") and self.kind.name.startswith("UPSTREAM_")
+
+    def __str__(self) -> str:
+        return self.message
 
 
 class ToolkitLoadError(ToolkitError):
     """
-    Raised when there is an error loading a toolkit.
+    Raised while importing / loading a toolkit package
+    (e.g. missing dependency, SyntaxError in module top-level code).
     """
 
-    pass
+    kind: ErrorKind = ErrorKind.TOOLKIT_LOAD_FAILED
+    can_retry: bool = False
 
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
 
-class ToolError(Exception):
-    """
-    Base class for all errors related to tools.
+    def create_message_prefix(self, toolkit_name: str) -> str:
+        return f"[{self.kind.value}] {type(self).__name__} when loading toolkit '{toolkit_name}': "
+
+
+class ToolError(ToolkitError):
     """
+    Any error related to an Arcade tool.
 
-    pass
+    Note: This class is an abstract class and cannot be instantiated directly.
+    """
 
 
+# ------  definition-time errors (tool developer's responsibility) ------
 class ToolDefinitionError(ToolError):
     """
-    Raised when there is an error in the definition of a tool.
+    Raised when there is an error in the definition/signature of a tool.
     """
 
-    pass
+    kind: ErrorKind = ErrorKind.TOOL_DEFINITION_BAD_DEFINITION
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+    def create_message_prefix(self, tool_name: str) -> str:
+        return f"[{self.kind.value}] {type(self).__name__} in definition of tool '{tool_name}': "
+
+
+class ToolInputSchemaError(ToolDefinitionError):
+    """Raised when there is an error in the schema of a tool's input parameter."""
+
+    kind: ErrorKind = ErrorKind.TOOL_DEFINITION_BAD_INPUT_SCHEMA
+
+
+class ToolOutputSchemaError(ToolDefinitionError):
+    """Raised when there is an error in the schema of a tool's output parameter."""
+
+    kind: ErrorKind = ErrorKind.TOOL_DEFINITION_BAD_OUTPUT_SCHEMA
 
 
 # ------  runtime errors ------
+class ToolRuntimeError(ToolError, RuntimeError):
+    """
+    Any failure starting from when the tool call begins until the tool call returns.
 
+    Note: This class should typically not be instantiated directly, but rather subclassed.
+    """
+
+    kind: ErrorKind = ErrorKind.TOOL_RUNTIME_FATAL
+    can_retry: bool = False
+    status_code: int | None = None
+    extra: dict[str, Any] | None = None
 
-class ToolRuntimeError(RuntimeError):
     def __init__(
         self,
         message: str,
-        developer_message: Optional[str] = None,
+        developer_message: str | None = None,
+        *,
+        extra: dict[str, Any] | None = None,
     ):
         super().__init__(message)
         self.message = message
-        self.developer_message = developer_message
+        self.developer_message = developer_message  # type: ignore[assignment]
+        self.extra = extra
 
-    def traceback_info(self) -> str | None:
-        # return the traceback information of the parent exception
+    def create_message_prefix(self, tool_name: str) -> str:
+        return f"[{self.kind.value}] {type(self).__name__} during execution of tool '{tool_name}': "
+
+    def stacktrace(self) -> str | None:
         if self.__cause__:
             return "\n".join(traceback.format_exception(self.__cause__))
         return None
 
+    def traceback_info(self) -> str | None:
+        """DEPRECATED: Use stacktrace() instead.
+
+        This method is deprecated and will be removed in a future major version.
+        """
+        return self.stacktrace()
 
+    # wire-format helper
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "message": self.message,
+            "developer_message": self.developer_message,
+            "kind": self.kind,
+            "can_retry": self.can_retry,
+            "status_code": self.status_code,
+            **(self.extra or {}),
+        }
+
+
+# 1. ------  serialization errors ------
+class ToolSerializationError(ToolRuntimeError):
+    """
+    Raised when there is an error serializing/marshalling the tool call arguments or return value.
+
+    Note: This class is not intended to be instantiated directly, but rather subclassed.
+    """
+
+
+class ToolInputError(ToolSerializationError):
+    """
+    Raised when there is an error parsing a tool call argument.
+    """
+
+    kind: ErrorKind = ErrorKind.TOOL_RUNTIME_BAD_INPUT_VALUE
+    status_code: int = 400
+
+
+class ToolOutputError(ToolSerializationError):
+    """
+    Raised when there is an error serializing a tool call return value.
+    """
+
+    kind: ErrorKind = ErrorKind.TOOL_RUNTIME_BAD_OUTPUT_VALUE
+    status_code: int = 500
+
+
+# 2. ------  tool-body errors ------
 class ToolExecutionError(ToolRuntimeError):
     """
-    Raised when there is an error executing a tool.
+    DEPRECATED: Raised when there is an error executing a tool.
+
+    ToolExecutionError is deprecated and will be removed in a future major version.
+    Use more specific error types instead:
+    - RetryableToolError for retryable errors
+    - ContextRequiredToolError for errors requiring user context
+    - FatalToolError for fatal/unexpected errors
+    - UpstreamError for upstream service errors
+    - UpstreamRateLimitError for upstream rate limiting errors
     """
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        developer_message: str | None = None,
+        *,
+        extra: dict[str, Any] | None = None,
+    ):
+        if type(self) is ToolExecutionError:
+            warnings.warn(
+                "ToolExecutionError is deprecated and will be removed in a future major version. "
+                "Use more specific error types instead: RetryableToolError, ContextRequiredToolError, "
+                "FatalToolError, UpstreamError, or UpstreamRateLimitError.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        super().__init__(message, developer_message=developer_message, extra=extra)
 
 
 class RetryableToolError(ToolExecutionError):
     """
-    Raised when a tool error is retryable.
+    Raised when a tool execution error is retryable.
     """
 
+    kind: ErrorKind = ErrorKind.TOOL_RUNTIME_RETRY
+    can_retry: bool = True
+
     def __init__(
         self,
         message: str,
-        developer_message: Optional[str] = None,
-        additional_prompt_content: Optional[str] = None,
-        retry_after_ms: Optional[int] = None,
+        developer_message: str | None = None,
+        additional_prompt_content: str | None = None,  # TODO: Make required in next major version
+        retry_after_ms: int | None = None,
+        extra: dict[str, Any] | None = None,
     ):
-        super().__init__(message, developer_message)
+        super().__init__(message, developer_message=developer_message, extra=extra)
         self.additional_prompt_content = additional_prompt_content
         self.retry_after_ms = retry_after_ms
 
 
-class ToolSerializationError(ToolRuntimeError):
+class ContextRequiredToolError(ToolExecutionError):
     """
-    Raised when there is an error executing a tool.
+    Raised when the combination of additional content from the tool AND
+    additional context from the end-user/orchestrator is required before retrying the tool.
+
+    This is typically used when an argument provided to the tool is invalid in some way,
+    and immediately prompting an LLM to retry the tool call is not desired.
     """
 
-    pass
+    kind: ErrorKind = ErrorKind.TOOL_RUNTIME_CONTEXT_REQUIRED
 
+    def __init__(
+        self,
+        message: str,
+        additional_prompt_content: str,
+        developer_message: str | None = None,
+        *,
+        extra: dict[str, Any] | None = None,
+    ):
+        super().__init__(message, developer_message=developer_message, extra=extra)
+        self.additional_prompt_content = additional_prompt_content
 
-class ToolInputError(ToolSerializationError):
+
+class FatalToolError(ToolExecutionError):
     """
-    Raised when there is an error in the input to a tool.
+    Raised when there is an unexpected or unknown error executing a tool.
     """
 
-    pass
+    status_code: int = 500
 
+    def __init__(
+        self,
+        message: str,
+        developer_message: str | None = None,
+        *,
+        extra: dict[str, Any] | None = None,
+    ):
+        super().__init__(message, developer_message=developer_message, extra=extra)
 
-class ToolOutputError(ToolSerializationError):
+
+# 3. ------  upstream errors in tool body------
+class UpstreamError(ToolExecutionError):
+    """
+    Error from an upstream service/API during tool execution.
+
+    This class handles all upstream failures except rate limiting.
+    The status_code and extra dict provide details about the specific error type.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        developer_message: str | None = None,
+        *,
+        status_code: int,
+        extra: dict[str, Any] | None = None,
+    ):
+        super().__init__(message, developer_message=developer_message, extra=extra)
+        self.status_code = status_code
+        # Determine retryability based on status code
+        self.can_retry = status_code >= 500 or status_code == 429
+        # Set appropriate error kind based on status
+        if status_code in (401, 403):
+            self.kind = ErrorKind.UPSTREAM_RUNTIME_AUTH_ERROR
+        elif status_code == 404:
+            self.kind = ErrorKind.UPSTREAM_RUNTIME_NOT_FOUND
+        elif status_code == 429:
+            self.kind = ErrorKind.UPSTREAM_RUNTIME_RATE_LIMIT
+        elif status_code >= 500:
+            self.kind = ErrorKind.UPSTREAM_RUNTIME_SERVER_ERROR
+        elif 400 <= status_code < 500:
+            self.kind = ErrorKind.UPSTREAM_RUNTIME_BAD_REQUEST
+        else:
+            self.kind = ErrorKind.UPSTREAM_RUNTIME_UNMAPPED
+
+
+class UpstreamRateLimitError(UpstreamError):
     """
-    Raised when there is an error in the output of a tool.
+    Rate limit error from an upstream service.
+
+    Special case of UpstreamError that includes retry_after_ms information.
     """
 
-    pass
+    kind: ErrorKind = ErrorKind.UPSTREAM_RUNTIME_RATE_LIMIT
+    can_retry: bool = True
+
+    def __init__(
+        self,
+        message: str,
+        retry_after_ms: int,
+        developer_message: str | None = None,
+        *,
+        extra: dict[str, Any] | None = None,
+    ):
+        super().__init__(message, status_code=429, developer_message=developer_message, extra=extra)
+        self.retry_after_ms = retry_after_ms

arcade_core/executor.py

@@ -6,11 +6,9 @@ from typing import Any
 from pydantic import BaseModel, ValidationError
 
 from arcade_core.errors import (
-    RetryableToolError,
     ToolInputError,
     ToolOutputError,
     ToolRuntimeError,
-    ToolSerializationError,
 )
 from arcade_core.output import output_factory
 from arcade_core.schema import (
@@ -69,31 +67,26 @@ class ToolExecutor:
             # return the output
             return output_factory.success(data=output, logs=tool_call_logs)
 
-        except RetryableToolError as e:
-            return output_factory.fail_retry(
-                message=e.message,
-                developer_message=e.developer_message,
-                additional_prompt_content=e.additional_prompt_content,
-                retry_after_ms=e.retry_after_ms,
-            )
-
-        except ToolSerializationError as e:
-            return output_factory.fail(message=e.message, developer_message=e.developer_message)
-
-        # should catch all tool exceptions due to the try/except in the tool decorator
         except ToolRuntimeError as e:
+            e.with_context(func.__name__)
             return output_factory.fail(
                 message=e.message,
                 developer_message=e.developer_message,
-                traceback_info=e.traceback_info(),
+                stacktrace=e.stacktrace(),
+                additional_prompt_content=getattr(e, "additional_prompt_content", None),
+                retry_after_ms=getattr(e, "retry_after_ms", None),
+                kind=e.kind,
+                can_retry=e.can_retry,
+                status_code=e.status_code,
+                extra=e.extra,
             )
 
         # if we get here we're in trouble
         except Exception as e:
             return output_factory.fail(
-                message="Error in execution",
+                message=f"Error in execution of '{func.__name__}'",
                 developer_message=str(e),
-                traceback_info=traceback.format_exc(),
+                stacktrace=traceback.format_exc(),
             )
 
     @staticmethod

arcade_core/output.py

@@ -1,7 +1,8 @@
-from typing import TypeVar
+from typing import Any, TypeVar
 
 from pydantic import BaseModel
 
+from arcade_core.errors import ErrorKind
 from arcade_core.schema import ToolCallError, ToolCallLog, ToolCallOutput
 from arcade_core.utils import coerce_empty_list_to_none
 
@@ -25,14 +26,27 @@ class ToolOutputFactory:
 
         The executor guarantees that `data` is either a string, a dict, or None.
         """
-        value: str | int | float | bool | dict | list[str] | None
+        value: str | int | float | bool | dict | list | None
         if data is None:
             value = ""
         elif hasattr(data, "result"):
-            value = getattr(data, "result", "")
+            result = getattr(data, "result", "")
+            # Handle None result the same way as None data
+            if result is None:
+                value = ""
+            # If the result is a BaseModel (e.g., from TypedDict conversion), convert to dict
+            elif isinstance(result, BaseModel):
+                value = result.model_dump()
+            # If the result is a list, check if it contains BaseModel objects
+            elif isinstance(result, list):
+                value = [
+                    item.model_dump() if isinstance(item, BaseModel) else item for item in result
+                ]
+            else:
+                value = result
         elif isinstance(data, BaseModel):
             value = data.model_dump()
-        elif isinstance(data, (str, int, float, bool, list)):
+        elif isinstance(data, (str, int, float, bool, list, dict)):
             value = data
         else:
             raise ValueError(f"Unsupported data output type: {type(data)}")
@@ -48,15 +62,26 @@ class ToolOutputFactory:
         *,
         message: str,
         developer_message: str | None = None,
-        traceback_info: str | None = None,
+        stacktrace: str | None = None,
         logs: list[ToolCallLog] | None = None,
+        additional_prompt_content: str | None = None,
+        retry_after_ms: int | None = None,
+        kind: ErrorKind = ErrorKind.UNKNOWN,
+        can_retry: bool = False,
+        status_code: int | None = None,
+        extra: dict[str, Any] | None = None,
     ) -> ToolCallOutput:
         return ToolCallOutput(
             error=ToolCallError(
                 message=message,
                 developer_message=developer_message,
-                can_retry=False,
-                traceback_info=traceback_info,
+                can_retry=can_retry,
+                additional_prompt_content=additional_prompt_content,
+                retry_after_ms=retry_after_ms,
+                stacktrace=stacktrace,
+                kind=kind,
+                status_code=status_code,
+                extra=extra,
             ),
             logs=coerce_empty_list_to_none(logs),
         )
@@ -68,9 +93,17 @@ class ToolOutputFactory:
         developer_message: str | None = None,
         additional_prompt_content: str | None = None,
         retry_after_ms: int | None = None,
-        traceback_info: str | None = None,
+        stacktrace: str | None = None,
         logs: list[ToolCallLog] | None = None,
+        kind: ErrorKind = ErrorKind.TOOL_RUNTIME_RETRY,
+        status_code: int = 500,
+        extra: dict[str, Any] | None = None,
     ) -> ToolCallOutput:
+        """
+        DEPRECATED: Use ToolOutputFactory.fail instead.
+        This method will be removed in version 3.0.0
+        """
+
         return ToolCallOutput(
             error=ToolCallError(
                 message=message,
@@ -78,7 +111,10 @@ class ToolOutputFactory:
                 can_retry=True,
                 additional_prompt_content=additional_prompt_content,
                 retry_after_ms=retry_after_ms,
-                traceback_info=traceback_info,
+                stacktrace=stacktrace,
+                kind=kind,
+                status_code=status_code,
+                extra=extra,
             ),
             logs=coerce_empty_list_to_none(logs),
         )

arcade_core/schema.py

@@ -5,6 +5,8 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, Field
 
+from arcade_core.errors import ErrorKind
+
 # allow for custom tool name separator
 TOOL_NAME_SEPARATOR = os.getenv("ARCADE_TOOL_NAME_SEPARATOR", ".")
 
@@ -390,6 +392,8 @@ class ToolCallError(BaseModel):
 
     message: str
     """The user-facing error message."""
+    kind: ErrorKind
+    """The error kind that uniquely identifies the kind of error."""
     developer_message: str | None = None
     """The developer-facing error details."""
     can_retry: bool = False
@@ -398,8 +402,27 @@ class ToolCallError(BaseModel):
     """Additional content to be included in the retry prompt."""
     retry_after_ms: int | None = None
     """The number of milliseconds (if any) to wait before retrying the tool call."""
-    traceback_info: str | None = None
-    """The traceback information for the tool call."""
+    stacktrace: str | None = None
+    """The stacktrace information for the tool call."""
+    status_code: int | None = None
+    """The HTTP status code of the error."""
+    extra: dict[str, Any] | None = None
+    """Additional information about the error."""
+
+    @property
+    def is_toolkit_error(self) -> bool:
+        """Check if this error originated from loading a toolkit."""
+        return self.kind.name.startswith("TOOLKIT_")
+
+    @property
+    def is_tool_error(self) -> bool:
+        """Check if this error originated from a tool."""
+        return self.kind.name.startswith("TOOL_")
+
+    @property
+    def is_upstream_error(self) -> bool:
+        """Check if this error originated from an upstream service."""
+        return self.kind.name.startswith("UPSTREAM_")
 
 
 class ToolCallRequiresAuthorization(BaseModel):
@@ -418,7 +441,7 @@ class ToolCallRequiresAuthorization(BaseModel):
 class ToolCallOutput(BaseModel):
     """The output of a tool invocation."""
 
-    value: str | int | float | bool | dict | list[str] | None = None
+    value: str | int | float | bool | dict | list | None = None
     """The value returned by the tool."""
     logs: list[ToolCallLog] | None = None
     """The logs that occurred during the tool invocation."""

{arcade_core-2.2.2.dist-info → arcade_core-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcade-core
-Version: 2.2.2
+Version: 2.4.0
 Summary: Arcade Core - Core library for Arcade platform
 Author-email: Arcade <dev@arcade.dev>
 License: MIT

{arcade_core-2.2.2.dist-info → arcade_core-2.4.0.dist-info}/RECORD

@@ -1,19 +1,19 @@
 arcade_core/__init__.py,sha256=1heu3AROAjpistehPzY2H-2nkj_IjQEh-vVlVOCRF1E,88
 arcade_core/annotations.py,sha256=Nst6aejLWXlpTu7GwzWETu1gQCG1XVAUR_qcFbNvyRc,198
-arcade_core/auth.py,sha256=-x7NipXciB6ASMjH_iTCdOl86s-R0JzQKeWkhDg1aDI,5613
-arcade_core/catalog.py,sha256=WVSTuJN2euY7PR6FBFADTR79teeetBJPFG06O-ohYjs,39492
+arcade_core/auth.py,sha256=On9sJPOxvHjKBxgKC1yqp7oijF6KYBsG6fG8KUw-9OY,5882
+arcade_core/catalog.py,sha256=X7_pZDXm-lEmQhfVwN4QVB2Q7IuO0qlM2avMJ3h66_k,41298
 arcade_core/config.py,sha256=e98XQAkYySGW9T_yrJg54BB8Wuq06GPVHp7xqe2d1vU,572
 arcade_core/config_model.py,sha256=GYO37yKi7ih6EYKPpX1Kl-K1XwM2JyEJguyaJ7j9TY8,4260
-arcade_core/errors.py,sha256=h4H1ck4TP-CDKPuRA5EVtRnplWwk9ofwFWE5h4AuMyg,2043
-arcade_core/executor.py,sha256=87fge4Mvvggn-ibVdxsin3IlPv5oRaZFdP70KYCIE7I,4550
-arcade_core/output.py,sha256=T5CP2wDdySgzaKspHRNA1g94nB6V6mbama0GmI9gUTI,2560
+arcade_core/errors.py,sha256=fsi7m6TQQSsdSNHl4rBoSN_YH3ZV910gjvBFqB207f4,13326
+arcade_core/executor.py,sha256=aFRqB4OdC4b8JJN3zekx0hOWYmihWHAZqVWVlSFXzE4,4308
+arcade_core/output.py,sha256=CMY1pHlQIR27Beiz2I-Yg1aO-P-pbsEbhBZ1RdYuflc,4040
 arcade_core/parse.py,sha256=gIo9w0iaKU_FpR9pFbUOxRfCK-cizg9SacoQC_jmgCc,1855
 arcade_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-arcade_core/schema.py,sha256=ldgw2GYIhdVMM_fbrvbtAWQYbtr23g3z71F0kt5SnH0,14666
+arcade_core/schema.py,sha256=Rvhgs5kEG8KkcpabSKhxXvZPNrFt_YVj815T70Iky3A,15477
 arcade_core/telemetry.py,sha256=qDv8T-wO8nFi0Qh93WKaPH1b6asfoJoyyfA7ZOxPnbA,5566
 arcade_core/toolkit.py,sha256=O-e8Pq6AKk78d78c16TPhEjufNuCjM_AWfLknpQvmy0,11108
 arcade_core/utils.py,sha256=anzEqj7Q_3dko-oY8U2QcH62rmQE7Y4fQBm0WjwLlIE,2980
 arcade_core/version.py,sha256=CpXi3jGlx23RvRyU7iytOMZrnspdWw4yofS8lpP1AJU,18
-arcade_core-2.2.2.dist-info/METADATA,sha256=RnM4R8_HgyjnYvmXJVJVt5xKSIH8cHAtYcgvrA5_9mE,2557
-arcade_core-2.2.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-arcade_core-2.2.2.dist-info/RECORD,,
+arcade_core-2.4.0.dist-info/METADATA,sha256=ln-4E-91IHvTVDf3FyavOKROlVx8lfiwzpIosCnqZnM,2557
+arcade_core-2.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+arcade_core-2.4.0.dist-info/RECORD,,