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

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,13 @@ 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. Tool descriptions are specified as docstrings for the tool function."
+            )
 
         # 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)
@@ -436,9 +451,11 @@ def create_input_definition(func: Callable) -> ToolInput:
     tool_context_param_name: str | None = None
 
     for _, param in inspect.signature(func, follow_wrapped=True).parameters.items():
-        if param.annotation is ToolContext:
+        ann = param.annotation
+        if isinstance(ann, type) and issubclass(ann, ToolContext):
+            # Soft guidance for developers using legacy 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 +500,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 +652,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 +671,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 +679,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 +694,12 @@ 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. Parameter descriptions are specified as string annotations using the typing.Annotated class."
+        )
 
     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 +815,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 +894,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 +914,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
@@ -965,15 +989,18 @@ def create_func_models(func: Callable) -> tuple[type[BaseModel], type[BaseModel]
     if asyncio.iscoroutinefunction(func) and hasattr(func, "__wrapped__"):
         func = func.__wrapped__
     for name, param in inspect.signature(func, follow_wrapped=True).parameters.items():
-        # Skip ToolContext parameters
-        if param.annotation is ToolContext:
+        # Skip ToolContext parameters (including subclasses like arcade_mcp_server.Context)
+        ann = param.annotation
+        if isinstance(ann, type) and issubclass(ann, ToolContext):
             continue
 
         # TODO make this cleaner
         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,18 +1008,23 @@ 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
 
 
-def determine_output_model(func: Callable) -> type[BaseModel]:  # noqa: C901
+def determine_output_model(func: Callable) -> type[BaseModel]:
     """
     Determine the output model for a function based on its return annotation.
     """
     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 +1040,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 +1084,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 +1101,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 +1112,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."),
+            ),
         )
 
 
@@ -1101,9 +1156,13 @@ def create_model_from_typeddict(typeddict_class: type, model_name: str) -> type[
 def to_tool_secret_requirements(
     secrets_requirement: list[str],
 ) -> list[ToolSecretRequirement]:
-    # Iterate through the list, de-dupe case-insensitively, and convert each string to a ToolSecretRequirement
-    unique_secrets = {name.lower(): name.lower() for name in secrets_requirement}.values()
-    return [ToolSecretRequirement(key=name) for name in unique_secrets]
+    # De-dupe case-insensitively but preserve the original casing for env var lookup
+    unique_map: dict[str, str] = {}
+    for name in secrets_requirement:
+        lowered = str(name).lower()
+        if lowered not in unique_map:
+            unique_map[lowered] = str(name)
+    return [ToolSecretRequirement(key=orig_name) for orig_name in unique_map.values()]
 
 
 def to_tool_metadata_requirements(

arcade_core/context.py

@@ -0,0 +1,128 @@
+"""
+Arcade Core Runtime Context Protocols
+
+Defines the developer-facing, transport-agnostic runtime context interfaces
+(namespaced APIs: logs, progress, resources, tools, prompts, sampling, UI,
+notifications) and the top-level ModelContext Protocol that aggregates them.
+
+Implementations live in runtime packages (e.g., arcade_mcp_server); tool authors should
+use `arcade_mcp_server.Context` for concrete usage.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+class LogsContext(Protocol):
+    async def debug(self, message: str, **kwargs: dict[str, Any]) -> None: ...
+
+    async def info(self, message: str, **kwargs: dict[str, Any]) -> None: ...
+
+    async def warning(self, message: str, **kwargs: dict[str, Any]) -> None: ...
+
+    async def error(self, message: str, **kwargs: dict[str, Any]) -> None: ...
+
+
+class ProgressContext(Protocol):
+    async def report(
+        self, progress: float, total: float | None = None, message: str | None = None
+    ) -> None: ...
+
+
+class ResourcesContext(Protocol):
+    async def list_(self) -> list[Any]: ...
+
+    async def get(self, uri: str) -> Any: ...
+
+    async def read(self, uri: str) -> list[Any]: ...
+
+    async def list_roots(self) -> list[Any]: ...
+
+    async def list_templates(self) -> list[Any]: ...
+
+
+class ToolsContext(Protocol):
+    async def list_(self) -> list[Any]: ...
+
+    async def call_raw(self, name: str, params: dict[str, Any]) -> BaseModel: ...
+
+
+class PromptsContext(Protocol):
+    async def list_(self) -> list[Any]: ...
+
+    async def get(self, name: str, arguments: dict[str, str] | None = None) -> Any: ...
+
+
+class SamplingContext(Protocol):
+    async def create_message(
+        self,
+        messages: str | list[str | Any],
+        system_prompt: str | None = None,
+        include_context: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        model_preferences: Any | None = None,
+    ) -> Any: ...
+
+
+class UIContext(Protocol):
+    async def elicit(self, message: str, schema: dict[str, Any] | None = None) -> Any: ...
+
+
+class NotificationsToolsContext(Protocol):
+    async def list_changed(self) -> None: ...
+
+
+class NotificationsResourcesContext(Protocol):
+    async def list_changed(self) -> None: ...
+
+
+class NotificationsPromptsContext(Protocol):
+    async def list_changed(self) -> None: ...
+
+
+class NotificationsContext(Protocol):
+    @property
+    def tools(self) -> NotificationsToolsContext: ...
+
+    @property
+    def resources(self) -> NotificationsResourcesContext: ...
+
+    @property
+    def prompts(self) -> NotificationsPromptsContext: ...
+
+
+@runtime_checkable
+class ModelContext(Protocol):
+    @property
+    def log(self) -> LogsContext: ...
+
+    @property
+    def progress(self) -> ProgressContext: ...
+
+    @property
+    def resources(self) -> ResourcesContext: ...
+
+    @property
+    def tools(self) -> ToolsContext: ...
+
+    @property
+    def prompts(self) -> PromptsContext: ...
+
+    @property
+    def sampling(self) -> SamplingContext: ...
+
+    @property
+    def ui(self) -> UIContext: ...
+
+    @property
+    def notifications(self) -> NotificationsContext: ...
+
+    @property
+    def request_id(self) -> str | None: ...
+
+    @property
+    def session_id(self) -> str | None: ...

arcade_core/converters/openai.py

@@ -0,0 +1,220 @@
+"""Converter for converting Arcade ToolDefinition to OpenAI tool schema."""
+
+from typing import Any, Literal, TypedDict
+
+from arcade_core.catalog import MaterializedTool
+from arcade_core.schema import InputParameter, ValueSchema
+
+# ----------------------------------------------------------------------------
+# Type definitions for JSON tool schemas used by OpenAI APIs.
+# Defines the proper types for tool schemas to ensure
+# compatibility with OpenAI's Responses and Chat Completions APIs.
+# ----------------------------------------------------------------------------
+
+
+class OpenAIFunctionParameterProperty(TypedDict, total=False):
+    """Type definition for a property within OpenAI function parameters schema."""
+
+    type: str | list[str]
+    """The JSON Schema type(s) for this property. Can be a single type or list for unions (e.g., ["string", "null"])."""
+
+    description: str
+    """Description of the property."""
+
+    enum: list[Any]
+    """Allowed values for enum properties."""
+
+    items: dict[str, Any]
+    """Schema for array items when type is 'array'."""
+
+    properties: dict[str, "OpenAIFunctionParameterProperty"]
+    """Nested properties when type is 'object'."""
+
+    required: list[str]
+    """Required fields for nested objects."""
+
+    additionalProperties: Literal[False]
+    """Must be False for strict mode compliance."""
+
+
+class OpenAIFunctionParameters(TypedDict, total=False):
+    """Type definition for OpenAI function parameters schema."""
+
+    type: Literal["object"]
+    """Must be 'object' for function parameters."""
+
+    properties: dict[str, OpenAIFunctionParameterProperty]
+    """The properties of the function parameters."""
+
+    required: list[str]
+    """List of required parameter names. In strict mode, all properties should be listed here."""
+
+    additionalProperties: Literal[False]
+    """Must be False for strict mode compliance."""
+
+
+class OpenAIFunctionSchema(TypedDict, total=False):
+    """Type definition for a function tool parameter matching OpenAI's API."""
+
+    name: str
+    """The name of the function to call."""
+
+    parameters: OpenAIFunctionParameters | None
+    """A JSON schema object describing the parameters of the function."""
+
+    strict: Literal[True]
+    """Always enforce strict parameter validation. Default `true`."""
+
+    description: str | None
+    """A description of the function.
+    Used by the model to determine whether or not to call the function.
+    """
+
+
+class OpenAIToolSchema(TypedDict):
+    """
+    Schema for a tool definition passed to OpenAI's `tools` parameter.
+    A tool wraps a callable function for function-calling. Each tool
+    includes a type (always 'function') and a `function` payload that
+    specifies the callable via `OpenAIFunctionSchema`.
+    """
+
+    type: Literal["function"]
+    """The type field, always 'function'."""
+
+    function: OpenAIFunctionSchema
+    """The function definition."""
+
+
+# Type alias for a list of openai tool schemas
+OpenAIToolList = list[OpenAIToolSchema]
+
+
+# ----------------------------------------------------------------------------
+# Converters
+# ----------------------------------------------------------------------------
+def to_openai(tool: MaterializedTool) -> OpenAIToolSchema:
+    """Convert a MaterializedTool to OpenAI JsonToolSchema format.
+
+    Args:
+        tool: The MaterializedTool to convert
+    Returns:
+        The OpenAI JsonToolSchema format (what is passed to the OpenAI API)
+    """
+    name = tool.definition.fully_qualified_name.replace(".", "_")
+    description = tool.description
+    parameters_schema = _convert_input_parameters_to_json_schema(tool.definition.input.parameters)
+    return _create_tool_schema(name, description, parameters_schema)
+
+
+def _create_tool_schema(
+    name: str, description: str, parameters: OpenAIFunctionParameters
+) -> OpenAIToolSchema:
+    """Create a properly typed tool schema.
+    Args:
+        name: The name of the function
+        description: Description of what the function does
+        parameters: JSON schema for the function parameters
+        strict: Whether to enforce strict validation (default: True for reliable function calls)
+    Returns:
+        A properly typed OpenAIToolSchema
+    """
+
+    function: OpenAIFunctionSchema = {
+        "name": name,
+        "description": description,
+        "parameters": parameters,
+        "strict": True,
+    }
+
+    tool: OpenAIToolSchema = {
+        "type": "function",
+        "function": function,
+    }
+
+    return tool
+
+
+def _convert_value_schema_to_json_schema(
+    value_schema: ValueSchema,
+) -> OpenAIFunctionParameterProperty:
+    """Convert Arcade ValueSchema to JSON Schema format."""
+    type_mapping = {
+        "string": "string",
+        "integer": "integer",
+        "number": "number",
+        "boolean": "boolean",
+        "json": "object",
+        "array": "array",
+    }
+
+    schema: OpenAIFunctionParameterProperty = {"type": type_mapping[value_schema.val_type]}
+
+    if value_schema.val_type == "array" and value_schema.inner_val_type:
+        items_schema: dict[str, Any] = {"type": type_mapping[value_schema.inner_val_type]}
+
+        # For arrays, enum should be applied to the items, not the array itself
+        if value_schema.enum:
+            items_schema["enum"] = value_schema.enum
+
+        schema["items"] = items_schema
+    else:
+        # Handle enum for non-array types
+        if value_schema.enum:
+            schema["enum"] = value_schema.enum
+
+    # Handle object properties
+    if value_schema.val_type == "json" and value_schema.properties:
+        schema["properties"] = {
+            name: _convert_value_schema_to_json_schema(nested_schema)
+            for name, nested_schema in value_schema.properties.items()
+        }
+
+    return schema
+
+
+def _convert_input_parameters_to_json_schema(
+    parameters: list[InputParameter],
+) -> OpenAIFunctionParameters:
+    """Convert list of InputParameter to JSON schema parameters object."""
+    if not parameters:
+        # Minimal JSON schema for a tool with no input parameters
+        return {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        }
+
+    properties = {}
+    required = []
+
+    for parameter in parameters:
+        param_schema = _convert_value_schema_to_json_schema(parameter.value_schema)
+
+        # For optional parameters in strict mode, we need to add "null" as a type option
+        if not parameter.required:
+            param_type = param_schema.get("type")
+            if isinstance(param_type, str):
+                # Convert single type to union with null
+                param_schema["type"] = [param_type, "null"]
+            elif isinstance(param_type, list) and "null" not in param_type:
+                param_schema["type"] = [*param_type, "null"]
+
+        if parameter.description:
+            param_schema["description"] = parameter.description
+        properties[parameter.name] = param_schema
+
+        # In strict mode, all parameters (including optional ones) go in required array
+        # Optional parameters are handled by adding "null" to their type
+        required.append(parameter.name)
+
+    json_schema: OpenAIFunctionParameters = {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+        "additionalProperties": False,
+    }
+    if not required:
+        del json_schema["required"]
+
+    return json_schema