arcade-core 2.0.0__py3-none-any.whl

arcade_core/config.py

@@ -0,0 +1,23 @@
+from functools import lru_cache
+
+from arcade_core.config_model import Config
+
+
+@lru_cache(maxsize=1)
+def get_config() -> Config:
+    """
+    Get the Arcade configuration.
+
+    This function is cached, so subsequent calls will return the same Config object
+    without reloading from the file, unless the cache is cleared.
+
+    remember to clear the cache if the configuration file is modified.
+    use `get_config.cache_clear()` to clear the cache.
+
+    Returns:
+        Config: The Arcade configuration.
+    """
+    return Config.load_from_file()
+
+
+config = get_config()

arcade_core/config_model.py

@@ -0,0 +1,146 @@
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+
+class BaseConfig(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+
+class ApiConfig(BaseConfig):
+    """
+    Arcade API configuration.
+    """
+
+    key: str
+    """
+    Arcade API key.
+    """
+    version: str = "v1"
+    """
+    Arcade API version.
+    """
+
+
+class UserConfig(BaseConfig):
+    """
+    Arcade user configuration.
+    """
+
+    email: str | None = None
+    """
+    User email.
+    """
+
+
+class Config(BaseConfig):
+    """
+    Configuration for Arcade.
+    """
+
+    api: ApiConfig
+    """
+    Arcade API configuration.
+    """
+    user: UserConfig | None = None
+    """
+    Arcade user configuration.
+    """
+
+    def __init__(self, **data: Any):
+        super().__init__(**data)
+
+    @classmethod
+    def get_config_dir_path(cls) -> Path:
+        """
+        Get the path to the Arcade configuration directory.
+        """
+        config_path = os.getenv("ARCADE_WORK_DIR") or Path.home() / ".arcade"
+        return Path(config_path).resolve()
+
+    @classmethod
+    def get_config_file_path(cls) -> Path:
+        """
+        Get the path to the Arcade configuration file.
+        """
+        return cls.get_config_dir_path() / "credentials.yaml"
+
+    @classmethod
+    def ensure_config_dir_exists(cls) -> None:
+        """
+        Create the configuration directory if it does not exist.
+        """
+        config_dir = Config.get_config_dir_path()
+        if not config_dir.exists():
+            config_dir.mkdir(parents=True, exist_ok=True)
+
+    @classmethod
+    def load_from_file(cls) -> "Config":
+        """
+        Load the configuration from the YAML file in the configuration directory.
+
+        If no configuration file exists, this method will create a new one with default values.
+        The default configuration includes:
+        - An empty API configuration
+        - A default Engine configuration (host: "api.arcade.dev", port: None, tls: True)
+        - No user configuration
+
+        Returns:
+            Config: The loaded or newly created configuration.
+
+        Raises:
+            ValueError: If the existing configuration file is invalid.
+        """
+        cls.ensure_config_dir_exists()
+
+        config_file_path = cls.get_config_file_path()
+
+        if not config_file_path.exists():
+            # Create a file using the default configuration
+            default_config = cls.model_construct(api=ApiConfig.model_construct())
+            default_config.save_to_file()
+
+        config_data = yaml.safe_load(config_file_path.read_text())
+
+        if config_data is None:
+            raise ValueError(
+                "Invalid credentials.yaml file. Please ensure it is a valid YAML file."
+            )
+
+        if "cloud" not in config_data:
+            raise ValueError("Invalid credentials.yaml file. Expected a 'cloud' key.")
+
+        try:
+            return cls(**config_data["cloud"])
+        except ValidationError as e:
+            # Get only the errors with {type:missing} and combine them
+            # into a nicely-formatted string message.
+            # Any other errors without {type:missing} should just be str()ed
+            missing_field_errors = [
+                ".".join(map(str, error["loc"]))
+                for error in e.errors()
+                if error["type"] == "missing"
+            ]
+            other_errors = [str(error) for error in e.errors() if error["type"] != "missing"]
+
+            missing_field_errors_str = ", ".join(missing_field_errors)
+            other_errors_str = "\n".join(other_errors)
+
+            pretty_str: str = "Invalid Arcade configuration."
+            if missing_field_errors_str:
+                pretty_str += f"\nMissing fields: {missing_field_errors_str}\n"
+            if other_errors_str:
+                pretty_str += f"\nOther errors:\n{other_errors_str}"
+
+            raise ValueError(pretty_str) from e
+
+    def save_to_file(self) -> None:
+        """
+        Save the configuration to the YAML file in the configuration directory.
+        """
+        Config.ensure_config_dir_exists()
+        config_file_path = Config.get_config_file_path()
+        config_file_path.write_text(yaml.dump(self.model_dump()))

arcade_core/errors.py

@@ -0,0 +1,103 @@
+import traceback
+from typing import Optional
+
+
+class ToolkitError(Exception):
+    """
+    Base class for all errors related to toolkits.
+    """
+
+    pass
+
+
+class ToolkitLoadError(ToolkitError):
+    """
+    Raised when there is an error loading a toolkit.
+    """
+
+    pass
+
+
+class ToolError(Exception):
+    """
+    Base class for all errors related to tools.
+    """
+
+    pass
+
+
+class ToolDefinitionError(ToolError):
+    """
+    Raised when there is an error in the definition of a tool.
+    """
+
+    pass
+
+
+# ------  runtime errors ------
+
+
+class ToolRuntimeError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        developer_message: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.developer_message = developer_message
+
+    def traceback_info(self) -> str | None:
+        # return the traceback information of the parent exception
+        if self.__cause__:
+            return "\n".join(traceback.format_exception(self.__cause__))
+        return None
+
+
+class ToolExecutionError(ToolRuntimeError):
+    """
+    Raised when there is an error executing a tool.
+    """
+
+    pass
+
+
+class RetryableToolError(ToolExecutionError):
+    """
+    Raised when a tool error is retryable.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        developer_message: Optional[str] = None,
+        additional_prompt_content: Optional[str] = None,
+        retry_after_ms: Optional[int] = None,
+    ):
+        super().__init__(message, developer_message)
+        self.additional_prompt_content = additional_prompt_content
+        self.retry_after_ms = retry_after_ms
+
+
+class ToolSerializationError(ToolRuntimeError):
+    """
+    Raised when there is an error executing a tool.
+    """
+
+    pass
+
+
+class ToolInputError(ToolSerializationError):
+    """
+    Raised when there is an error in the input to a tool.
+    """
+
+    pass
+
+
+class ToolOutputError(ToolSerializationError):
+    """
+    Raised when there is an error in the output of a tool.
+    """
+
+    pass

arcade_core/executor.py

@@ -0,0 +1,129 @@
+import asyncio
+import traceback
+from typing import Any, Callable
+
+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 ToolCallLog, ToolCallOutput, ToolContext, ToolDefinition
+
+
+class ToolExecutor:
+    @staticmethod
+    async def run(
+        func: Callable,
+        definition: ToolDefinition,
+        input_model: type[BaseModel],
+        output_model: type[BaseModel],
+        context: ToolContext,
+        *args: Any,
+        **kwargs: Any,
+    ) -> ToolCallOutput:
+        """
+        Execute a callable function with validated inputs and outputs via Pydantic models.
+        """
+        # only gathering deprecation log for now
+        tool_call_logs = []
+        if definition.deprecation_message is not None:
+            tool_call_logs.append(
+                ToolCallLog(
+                    message=definition.deprecation_message, level="warning", subtype="deprecation"
+                )
+            )
+
+        try:
+            # serialize the input model
+            inputs = await ToolExecutor._serialize_input(input_model, **kwargs)
+
+            # prepare the arguments for the function call
+            func_args = inputs.model_dump()
+
+            # inject ToolContext, if the target function supports it
+            if definition.input.tool_context_parameter_name is not None:
+                func_args[definition.input.tool_context_parameter_name] = context
+
+            # execute the tool function
+            if asyncio.iscoroutinefunction(func):
+                results = await func(**func_args)
+            else:
+                results = func(**func_args)
+
+            # serialize the output model
+            output = await ToolExecutor._serialize_output(output_model, results)
+
+            # 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:
+            return output_factory.fail(
+                message=e.message,
+                developer_message=e.developer_message,
+                traceback_info=e.traceback_info(),
+            )
+
+        # if we get here we're in trouble
+        except Exception as e:
+            return output_factory.fail(
+                message="Error in execution",
+                developer_message=str(e),
+                traceback_info=traceback.format_exc(),
+            )
+
+    @staticmethod
+    async def _serialize_input(input_model: type[BaseModel], **kwargs: Any) -> BaseModel:
+        """
+        Serialize the input to a tool function.
+        """
+        try:
+            # TODO Logging and telemetry
+
+            # build in the input model to the tool function
+            inputs = input_model(**kwargs)
+
+        except ValidationError as e:
+            raise ToolInputError(
+                message="Error in tool input deserialization", developer_message=str(e)
+            ) from e
+
+        return inputs
+
+    @staticmethod
+    async def _serialize_output(output_model: type[BaseModel], results: dict) -> BaseModel:
+        """
+        Serialize the output of a tool function.
+        """
+        # TODO how to type this the results object?
+        # TODO how to ensure `results` contains only safe (serializable) stuff?
+        try:
+            # TODO Logging and telemetry
+
+            # build the output model
+            output = output_model(**{"result": results})
+
+        except ValidationError as e:
+            raise ToolOutputError(
+                message="Failed to serialize tool output",
+                developer_message=f"Validation error occurred while serializing tool output: {e!s}. "
+                f"Please ensure the tool's output matches the expected schema.",
+            ) from e
+
+        return output

arcade_core/output.py

@@ -0,0 +1,64 @@
+from typing import TypeVar
+
+from arcade_core.schema import ToolCallError, ToolCallLog, ToolCallOutput
+from arcade_core.utils import coerce_empty_list_to_none
+
+T = TypeVar("T")
+
+
+class ToolOutputFactory:
+    """
+    Singleton pattern for unified return method from tools.
+    """
+
+    def success(
+        self,
+        *,
+        data: T | None = None,
+        logs: list[ToolCallLog] | None = None,
+    ) -> ToolCallOutput:
+        value = getattr(data, "result", "") if data else ""
+        logs = coerce_empty_list_to_none(logs)
+        return ToolCallOutput(value=value, logs=logs)
+
+    def fail(
+        self,
+        *,
+        message: str,
+        developer_message: str | None = None,
+        traceback_info: str | None = None,
+        logs: list[ToolCallLog] | None = None,
+    ) -> ToolCallOutput:
+        return ToolCallOutput(
+            error=ToolCallError(
+                message=message,
+                developer_message=developer_message,
+                can_retry=False,
+                traceback_info=traceback_info,
+            ),
+            logs=coerce_empty_list_to_none(logs),
+        )
+
+    def fail_retry(
+        self,
+        *,
+        message: str,
+        developer_message: str | None = None,
+        additional_prompt_content: str | None = None,
+        retry_after_ms: int | None = None,
+        traceback_info: str | None = None,
+        logs: list[ToolCallLog] | None = None,
+    ) -> ToolCallOutput:
+        return ToolCallOutput(
+            error=ToolCallError(
+                message=message,
+                developer_message=developer_message,
+                can_retry=True,
+                additional_prompt_content=additional_prompt_content,
+                retry_after_ms=retry_after_ms,
+            ),
+            logs=coerce_empty_list_to_none(logs),
+        )
+
+
+output_factory = ToolOutputFactory()

arcade_core/parse.py

@@ -0,0 +1,63 @@
+import ast
+from pathlib import Path
+from typing import Optional, Union
+
+
+def load_ast_tree(filepath: str | Path) -> ast.AST:
+    """
+    Load and parse the Abstract Syntax Tree (AST) from a Python file.
+
+    """
+    try:
+        with open(filepath) as file:
+            return ast.parse(file.read(), filename=filepath)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"File {filepath} not found")
+
+
+def get_function_name_if_decorated(
+    node: Union[ast.FunctionDef, ast.AsyncFunctionDef],
+) -> Optional[str]:
+    """
+    Check if a function has a decorator.
+    """
+    decorator_ids = {"arc.tool", "tool"}
+    for decorator in node.decorator_list:
+        # if the function is decorated and the decorator is
+        # either called, or placed on the function
+        if (
+            (isinstance(decorator, ast.Name) and decorator.id in decorator_ids)
+            or (
+                isinstance(decorator, ast.Attribute)
+                and isinstance(decorator.value, ast.Name)
+                and f"{decorator.value.id}.{decorator.attr}" in decorator_ids
+            )
+            or (
+                isinstance(decorator, ast.Call)
+                and isinstance(decorator.func, ast.Name)
+                and decorator.func.id in decorator_ids
+            )
+        ):
+            return node.name
+    return None
+
+
+def get_tools_from_file(filepath: str | Path) -> list[str]:
+    """
+    Retrieve tools from a Python file.
+    """
+    tree = load_ast_tree(filepath)
+    return get_tools_from_ast(tree)
+
+
+def get_tools_from_ast(tree: ast.AST) -> list[str]:
+    """
+    Retrieve tools from Python source code.
+    """
+    tools = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            tool_name = get_function_name_if_decorated(node)
+            if tool_name:
+                tools.append(tool_name)
+    return tools