arcade-core 2.3.0__py3-none-any.whl → 2.5.0rc1__py3-none-any.whl

arcade_core/discovery.py

@@ -0,0 +1,253 @@
+"""
+Discovery utilities for Arcade Tools.
+
+Provides modular, testable functions to discover toolkits and local tool files,
+load modules, collect tools, and build a ToolCatalog.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from loguru import logger
+
+from arcade_core.catalog import ToolCatalog
+from arcade_core.parse import get_tools_from_file
+from arcade_core.toolkit import Toolkit, ToolkitLoadError
+
+DISCOVERY_PATTERNS = ["*.py", "tools/*.py", "arcade_tools/*.py", "tools/**/*.py"]
+FILTER_PATTERNS = ["_test.py", "test_*.py", "__pycache__", "*.lock", "*.egg-info", "*.pyc"]
+
+
+def normalize_package_name(package_name: str) -> str:
+    """Normalize a package name for import resolution."""
+    return package_name.lower().replace("-", "_")
+
+
+def load_toolkit_from_package(package_name: str, show_packages: bool = False) -> Toolkit:
+    """Attempt to load a Toolkit from an installed package name."""
+    toolkit = Toolkit.from_package(package_name)
+    if show_packages:
+        logger.info(f"Loading package: {toolkit.name}")
+    return toolkit
+
+
+def load_package(package_name: str, show_packages: bool = False) -> Toolkit:
+    """Load a toolkit for a specific package name.
+
+    Raises ToolkitLoadError if the package is not found.
+    """
+    normalized = normalize_package_name(package_name)
+    try:
+        return load_toolkit_from_package(normalized, show_packages)
+    except ToolkitLoadError:
+        return load_toolkit_from_package(f"arcade_{normalized}", show_packages)
+
+
+def find_candidate_tool_files(root: Path | None = None) -> list[Path]:
+    """Find candidate Python files for auto-discovery in common locations."""
+    cwd = root or Path.cwd()
+
+    candidates: list[Path] = []
+    for pattern in DISCOVERY_PATTERNS:
+        candidates.extend(cwd.glob(pattern))
+    # Deduplicate candidates (same file might match multiple patterns)
+    unique_candidates = list(set(candidates))
+    # Filter out private, cache, and tests
+    return [
+        p for p in unique_candidates if not any(p.match(pattern) for pattern in FILTER_PATTERNS)
+    ]
+
+
+def analyze_files_for_tools(files: list[Path]) -> list[tuple[Path, list[str]]]:
+    """Parse files with a fast AST pass to find declared @tool function names."""
+    results: list[tuple[Path, list[str]]] = []
+    for file_path in files:
+        try:
+            names = get_tools_from_file(file_path)
+            if names:
+                logger.info(f"Found {len(names)} tool(s) in {file_path.name}: {', '.join(names)}")
+                results.append((file_path, names))
+        except Exception:
+            logger.exception(f"Could not parse {file_path}")
+    return results
+
+
+def load_module_from_path(file_path: Path) -> ModuleType:
+    """Dynamically import a Python module from a file path."""
+    import sys
+
+    # Add the directory containing the file to sys.path temporarily
+    # This allows local imports to work
+    file_dir = str(file_path.parent)
+    path_added = False
+    if file_dir not in sys.path:
+        sys.path.insert(0, file_dir)
+        path_added = True
+
+    try:
+        spec = importlib.util.spec_from_file_location(
+            f"_tools_{file_path.stem}",
+            file_path,
+        )
+        if not spec or not spec.loader:
+            raise ToolkitLoadError(f"Unable to create import spec for {file_path}")
+
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)
+        except Exception:
+            logger.exception(f"Failed to load {file_path}")
+            raise ToolkitLoadError(f"Failed to load {file_path}")
+
+        return module
+    finally:
+        # Remove the path we added
+        if path_added and file_dir in sys.path:
+            sys.path.remove(file_dir)
+
+
+def collect_tools_from_modules(
+    files_with_tools: list[tuple[Path, list[str]]],
+) -> list[tuple[Any, ModuleType]]:
+    """Load modules and collect the expected tool callables.
+
+    Returns a list of (callable, module) pairs.
+    """
+    discovered: list[tuple[Any, ModuleType]] = []
+
+    for file_path, expected_names in files_with_tools:
+        logger.debug(f"Loading tools from {file_path}...")
+        try:
+            module = load_module_from_path(file_path)
+        except ToolkitLoadError:
+            continue
+
+        for name in expected_names:
+            if hasattr(module, name):
+                attr = getattr(module, name)
+                if callable(attr) and hasattr(attr, "__tool_name__"):
+                    discovered.append((attr, module))
+                else:
+                    logger.warning(
+                        f"Expected {name} to be a tool but it wasn't (missing __tool_name__)\n\n"
+                    )
+    return discovered
+
+
+def build_minimal_toolkit(
+    server_name: str | None,
+    server_version: str | None,
+    description: str | None = None,
+) -> Toolkit:
+    """Create a minimal Toolkit to host locally discovered tools."""
+    name = server_name or "ArcadeMCP"
+    version = server_version or "0.1.0dev"
+    pkg = f"{name}.{Path.cwd().name}"
+    desc = description or f"MCP Server for {name} version {version}"
+    return Toolkit(name=name, package_name=pkg, version=version, description=desc)
+
+
+def build_catalog_from_toolkits(toolkits: list[Toolkit]) -> ToolCatalog:
+    """Create a ToolCatalog and add the provided toolkits."""
+    catalog = ToolCatalog()
+    for tk in toolkits:
+        catalog.add_toolkit(tk)
+    return catalog
+
+
+def add_discovered_tools(
+    catalog: ToolCatalog,
+    toolkit: Toolkit,
+    tools: list[tuple[Any, ModuleType]],
+) -> None:
+    """Add discovered local tools to the catalog, preserving module context."""
+    for tool_func, module in tools:
+        if module.__name__ not in __import__("sys").modules:
+            __import__("sys").modules[module.__name__] = module
+        catalog.add_tool(tool_func, toolkit, module)
+
+
+def load_toolkits_for_option(tool_package: str, show_packages: bool = False) -> list[Toolkit]:
+    """
+    Load toolkits for a given package option.
+
+    Args:
+        tool_package: Package name or comma-separated list of package names
+        show_packages: Whether to log loaded packages
+
+    Returns:
+        List of loaded toolkits
+    """
+    toolkits = []
+    packages = [p.strip() for p in tool_package.split(",")]
+
+    for package in packages:
+        try:
+            toolkit = load_package(package, show_packages)
+            toolkits.append(toolkit)
+        except ToolkitLoadError as e:
+            logger.warning(f"Failed to load package '{package}': {e}")
+
+    return toolkits
+
+
+def load_all_installed_toolkits(show_packages: bool = False) -> list[Toolkit]:
+    """
+    Discover and load all installed arcade toolkits.
+
+    Args:
+        show_packages: Whether to log loaded packages
+
+    Returns:
+        List of all installed toolkits
+    """
+    toolkits = Toolkit.find_all_arcade_toolkits()
+
+    if show_packages:
+        for toolkit in toolkits:
+            logger.info(f"Loading package: {toolkit.name}")
+
+    return toolkits
+
+
+def discover_tools(
+    tool_package: str | None = None,
+    show_packages: bool = False,
+    discover_installed: bool = False,
+    server_name: str | None = None,
+    server_version: str | None = None,
+) -> ToolCatalog:
+    """High-level discovery that returns a ToolCatalog.
+
+    This function is pure (does not sys.exit); callers should handle errors.
+    """
+    # 1) Package-based discovery
+    if tool_package:
+        toolkits = load_toolkits_for_option(tool_package, show_packages)
+        return build_catalog_from_toolkits(toolkits)
+
+    # 2) Discover all installed packages
+    if discover_installed:
+        toolkits = load_all_installed_toolkits(show_packages)
+        return build_catalog_from_toolkits(toolkits)
+
+    # 3) Local file discovery
+    logger.info("Auto-discovering tools from current directory")
+    files = find_candidate_tool_files()
+    if not files:
+        # Return empty catalog; caller can decide how to handle
+        return ToolCatalog()
+
+    files_with_tools = analyze_files_for_tools(files)
+    if not files_with_tools:
+        return ToolCatalog()
+
+    discovered = collect_tools_from_modules(files_with_tools)
+    catalog = ToolCatalog()
+    toolkit = build_minimal_toolkit(server_name, server_version)
+    add_discovered_tools(catalog, toolkit, discovered)
+    return catalog

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