arcade-core 2.4.0__tar.gz → 2.5.0rc1__tar.gz

{arcade_core-2.4.0 → arcade_core-2.5.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcade-core
-Version: 2.4.0
+Version: 2.5.0rc1
 Summary: Arcade Core - Core library for Arcade platform
 Author-email: Arcade <dev@arcade.dev>
 License: MIT
@@ -14,9 +14,6 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: loguru>=0.7.0
-Requires-Dist: opentelemetry-exporter-otlp-proto-common==1.28.2
-Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.28.2
-Requires-Dist: opentelemetry-instrumentation-fastapi==0.49b2
 Requires-Dist: packaging>=24.1
 Requires-Dist: pydantic>=2.7.0
 Requires-Dist: pyjwt>=2.8.0

{arcade_core-2.4.0 → arcade_core-2.5.0rc1}/arcade_core/catalog.py

@@ -405,7 +405,9 @@ 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:
@@ -449,7 +451,9 @@ 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 ToolInputSchemaError(
                     f"Only one ToolContext parameter is supported, but tool {func.__name__} has multiple."
@@ -690,7 +694,9 @@ def extract_field_info(param: inspect.Parameter) -> ToolParamInfo:
 
     # Final reality check
     if param_info.description is None:
-        raise ToolInputSchemaError(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 ToolInputSchemaError(f"Unknown parameter type: {param_info.field_type}")
@@ -983,8 +989,9 @@ 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
@@ -1004,7 +1011,7 @@ def create_func_models(func: Callable) -> tuple[type[BaseModel], type[BaseModel]
     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.
     """
@@ -1149,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-2.5.0rc1/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-2.5.0rc1/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

arcade_core-2.5.0rc1/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-2.4.0 → arcade_core-2.5.0rc1}/arcade_core/parse.py

@@ -36,6 +36,18 @@ def get_function_name_if_decorated(
                 and isinstance(decorator.func, ast.Name)
                 and decorator.func.id in decorator_ids
             )
+            # Support MCPApp tools. e.g., @app.tool or @app.tool(...)
+            or (
+                isinstance(decorator, ast.Attribute)
+                and decorator.attr == "tool"
+                and isinstance(decorator.value, ast.Name)
+            )
+            or (
+                isinstance(decorator, ast.Call)
+                and isinstance(decorator.func, ast.Attribute)
+                and decorator.func.attr == "tool"
+                and isinstance(decorator.func.value, ast.Name)
+            )
         ):
             return node.name
     return None

{arcade_core-2.4.0 → arcade_core-2.5.0rc1}/arcade_core/schema.py

@@ -1,3 +1,21 @@
+"""
+Arcade Core Schema
+
+Defines transport-agnostic tool schemas and runtime context protocols used
+across Arcade libraries. This includes:
+
+- Tool and toolkit specifications (parameters, outputs, requirements)
+- Transport-agnostic ToolContext carrying authorization, secrets, metadata
+- Runtime ModelContext Protocol and its namespaced sub-protocols for logs,
+  progress, resources, tools, prompts, sampling, UI, and notifications
+
+Note: ToolContext does not embed runtime capabilities; those are provided by
+implementations of ModelContext (e.g., in arcade-mcp-server) that subclasses ToolContext
+to expose the namespaced APIs to tools without changing function signatures.
+"""
+
+from __future__ import annotations
+
 import os
 from dataclasses import dataclass
 from enum import Enum
@@ -23,10 +41,10 @@ class ValueSchema(BaseModel):
     enum: list[str] | None = None
     """The list of possible values for the value, if it is a closed list."""
 
-    properties: dict[str, "ValueSchema"] | None = None
+    properties: dict[str, ValueSchema] | None = None
     """For object types (json), the schema of nested properties."""
 
-    inner_properties: dict[str, "ValueSchema"] | None = None
+    inner_properties: dict[str, ValueSchema] | None = None
     """For array types with json items, the schema of properties for each array item."""
 
     description: str | None = None
@@ -100,7 +118,7 @@ class ToolAuthRequirement(BaseModel):
     # or
     #    client.auth.authorize(provider=AuthProvider.google, scopes=["profile", "email"])
     #
-    # The Arcade SDK translates these into the appropriate provider ID (Google) and type (OAuth2).
+    # The Arcade TDK translates these into the appropriate provider ID (Google) and type (OAuth2).
     # The only time the developer will set these is if they are using a custom auth provider.
     provider_id: str | None = None
     """The provider ID configured in Arcade that acts as an alias to well-known configuration."""
@@ -200,7 +218,7 @@ class FullyQualifiedName:
             (self.toolkit_version or "").lower(),
         ))
 
-    def equals_ignoring_version(self, other: "FullyQualifiedName") -> bool:
+    def equals_ignoring_version(self, other: FullyQualifiedName) -> bool:
         """Check if two fully-qualified tool names are equal, ignoring the version."""
         return (
             self.name.lower() == other.name.lower()
@@ -208,7 +226,7 @@ class FullyQualifiedName:
         )
 
     @staticmethod
-    def from_toolkit(tool_name: str, toolkit: ToolkitDefinition) -> "FullyQualifiedName":
+    def from_toolkit(tool_name: str, toolkit: ToolkitDefinition) -> FullyQualifiedName:
         """Creates a fully-qualified tool name from a tool name and a ToolkitDefinition."""
         return FullyQualifiedName(tool_name, toolkit.name, toolkit.version)
 
@@ -298,7 +316,16 @@ class ToolMetadataItem(BaseModel):
 
 
 class ToolContext(BaseModel):
-    """The context for a tool invocation."""
+    """The context for a tool invocation.
+
+    This type is transport-agnostic and contains only authorization,
+    secret, and metadata information needed by the tool. Runtime-specific
+    capabilities (logging, resources, etc.) are provided by a separate
+    runtime context that wraps this object.
+
+    Recommendation: For new tools, annotate the parameter as
+    `arcade_mcp_server.Context` to access namespaced runtime APIs directly.
+    """
 
     authorization: ToolAuthorizationContext | None = None
     """The authorization context for the tool invocation that requires authorization."""
@@ -312,16 +339,35 @@ class ToolContext(BaseModel):
     user_id: str | None = None
     """The user ID for the tool invocation (if any)."""
 
+    model_config = {"arbitrary_types_allowed": True}
+
+    def set_secret(self, key: str, value: str) -> None:
+        """Add or update a secret to the tool context."""
+        if self.secrets is None:
+            self.secrets = []
+        # Update existing or add new
+        for secret in self.secrets:
+            if secret.key == key:
+                secret.value = value
+                return
+        self.secrets.append(ToolSecretItem(key=key, value=value))
+
     def get_auth_token_or_empty(self) -> str:
         """Retrieve the authorization token, or return an empty string if not available."""
         return self.authorization.token if self.authorization and self.authorization.token else ""
 
     def get_secret(self, key: str) -> str:
-        """Retrieve the secret for the tool invocation."""
+        """Retrieve the secret for the tool invocation.
+
+        Raises a ValueError if the secret is not found.
+        """
         return self._get_item(key, self.secrets, "secret")
 
     def get_metadata(self, key: str) -> str:
-        """Retrieve the metadata for the tool invocation."""
+        """Retrieve the metadata for the tool invocation.
+
+        Raises a ValueError if the metadata is not found.
+        """
         return self._get_item(key, self.metadata, "metadata")
 
     def _get_item(
@@ -335,21 +381,14 @@ class ToolContext(BaseModel):
                 f"{item_name.capitalize()} key passed to get_{item_name} cannot be empty."
             )
         if not items:
-            raise ValueError(f"{item_name.capitalize()}s not found in context.")
+            raise ValueError(f"{item_name.capitalize()} '{key}' not found in context.")
 
         normalized_key = key.lower()
         for item in items:
             if item.key.lower() == normalized_key:
                 return item.value
 
-        raise ValueError(f"{item_name.capitalize()} {key} not found in context.")
-
-    def set_secret(self, key: str, value: str) -> None:
-        """Set a secret for the tool invocation."""
-        if not self.secrets:
-            self.secrets = []
-        secret = ToolSecretItem(key=str(key), value=str(value))
-        self.secrets.append(secret)
+        raise ValueError(f"{item_name.capitalize()} '{key}' not found in context.")
 
 
 class ToolCallRequest(BaseModel):

{arcade_core-2.4.0 → arcade_core-2.5.0rc1}/arcade_core/toolkit.py

@@ -6,6 +6,7 @@ import types
 from collections import defaultdict
 from pathlib import Path, PurePosixPath, PureWindowsPath
 
+import toml
 from pydantic import BaseModel, ConfigDict, field_validator
 
 from arcade_core.errors import ToolkitLoadError
@@ -59,6 +60,71 @@ class Toolkit(BaseModel):
         """
         return cls.from_package(module.__name__)
 
+    @classmethod
+    def from_directory(cls, directory: Path) -> "Toolkit":
+        """
+        Load a Toolkit from a directory.
+        """
+        pyproject_path = directory / "pyproject.toml"
+        if not pyproject_path.exists():
+            raise ToolkitLoadError(f"pyproject.toml not found in {directory}")
+
+        try:
+            with open(pyproject_path) as f:
+                pyproject_data = toml.load(f)
+
+            project_data = pyproject_data.get("project", {})
+            name = project_data.get("name")
+            if not name:
+
+                def _missing_name_error() -> ToolkitLoadError:
+                    return ToolkitLoadError("name not found in pyproject.toml")
+
+                raise _missing_name_error()  # noqa: TRY301
+
+            package_name = name
+            version = project_data.get("version", "0.0.0")
+            description = project_data.get("description", "")
+            authors = project_data.get("authors", [])
+            author_names = [author.get("name", "") for author in authors]
+
+            # For homepage and repository, you might need to look under project.urls
+            urls = project_data.get("urls", {})
+            homepage = urls.get("Homepage")
+            repo = urls.get("Repository")
+
+        except Exception as e:
+            raise ToolkitLoadError(f"Failed to load metadata from {pyproject_path}: {e}")
+
+        # Determine the actual package directory (supports src/ layout and flat layout)
+        package_dir = directory
+        try:
+            src_candidate = directory / "src" / package_name
+            flat_candidate = directory / package_name
+            if src_candidate.is_dir():
+                package_dir = src_candidate
+            elif flat_candidate.is_dir():
+                package_dir = flat_candidate
+            else:
+                # Fallback to the provided directory; tools_from_directory will de-duplicate prefixes
+                package_dir = directory
+        except Exception:
+            package_dir = directory
+
+        toolkit = cls(
+            name=name,
+            package_name=package_name,
+            version=version,
+            description=description,
+            author=author_names,
+            homepage=homepage,
+            repository=repo,
+        )
+
+        toolkit.tools = cls.tools_from_directory(package_dir, package_name)
+
+        return toolkit
+
     @classmethod
     def from_package(cls, package: str) -> "Toolkit":
         """
@@ -232,9 +298,14 @@ class Toolkit(BaseModel):
         for module_path in modules:
             relative_path = module_path.relative_to(package_dir)
             cls.validate_file(module_path)
-            import_path = ".".join(relative_path.with_suffix("").parts)
-            import_path = f"{package_name}.{import_path}"
-            tools[import_path] = get_tools_from_file(str(module_path))
+            # Build import path and avoid duplicating the package prefix if it already exists
+            relative_parts = relative_path.with_suffix("").parts
+            import_path = ".".join(relative_parts)
+            if relative_parts and relative_parts[0] == package_name:
+                full_import_path = import_path
+            else:
+                full_import_path = f"{package_name}.{import_path}" if import_path else package_name
+            tools[full_import_path] = get_tools_from_file(str(module_path))
 
         if not tools:
             raise ToolkitLoadError(f"No tools found in package {package_name}")

{arcade_core-2.4.0 → arcade_core-2.5.0rc1}/arcade_core/utils.py

@@ -4,6 +4,7 @@ import ast
 import inspect
 import re
 from collections.abc import Callable, Iterable
+from textwrap import dedent
 from types import UnionType
 from typing import Any, Literal, TypeVar, Union, get_args, get_origin
 
@@ -75,7 +76,9 @@ def does_function_return_value(func: Callable) -> bool:
     if source is None:
         raise ValueError("Source code not found")
 
-    tree = ast.parse(source)
+    # dedent in case the function is an inner function
+    dedented_source = dedent(source)
+    tree = ast.parse(dedented_source)
 
     class ReturnVisitor(ast.NodeVisitor):
         def __init__(self) -> None:

{arcade_core-2.4.0 → arcade_core-2.5.0rc1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arcade-core"
-version = "2.4.0"
+version = "2.5.0rc1"
 description = "Arcade Core - Core library for Arcade platform"
 readme = "README.md"
 license = {text = "MIT"}
@@ -28,9 +28,6 @@ dependencies = [
     "types-python-dateutil==2.9.0.20241003",
     "types-pytz==2024.2.0.20241003",
     "types-toml==0.10.8.20240310",
-    "opentelemetry-instrumentation-fastapi==0.49b2",
-    "opentelemetry-exporter-otlp-proto-http==1.28.2",
-    "opentelemetry-exporter-otlp-proto-common==1.28.2",
 ]
 
 [project.optional-dependencies]

arcade_core-2.4.0/arcade_core/telemetry.py

@@ -1,130 +0,0 @@
-import logging
-import os
-import urllib.parse
-from typing import Optional
-
-from fastapi import FastAPI
-from opentelemetry import _logs, trace
-from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
-from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
-from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
-from opentelemetry.metrics import Meter, get_meter_provider, set_meter_provider
-from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
-from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
-from opentelemetry.sdk.metrics import MeterProvider
-from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
-from opentelemetry.sdk.resources import SERVICE_NAME, Resource
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor
-
-
-class ShutdownError(Exception):
-    pass
-
-
-class OTELHandler:
-    def __init__(self, enable: bool = True, log_level: int = logging.INFO):
-        self.enable = enable
-        self.log_level = log_level
-        self._tracer_provider: Optional[TracerProvider] = None
-        self._tracer_span_exporter: Optional[OTLPSpanExporter] = None
-        self._meter_provider: Optional[MeterProvider] = None
-        self._meter_reader: Optional[PeriodicExportingMetricReader] = None
-        self._otlp_metric_exporter: Optional[OTLPMetricExporter] = None
-        self._logger_provider: Optional[LoggerProvider] = None
-        self._log_processor: Optional[BatchLogRecordProcessor] = None
-        self.environment = os.environ.get("ARCADE_ENVIRONMENT", "local")
-
-    def instrument_app(self, app: FastAPI) -> None:
-        if self.enable:
-            logging.info(
-                "🔎 Initializing OpenTelemetry. Use environment variables to configure the connection"
-            )
-            self.resource = Resource(
-                attributes={SERVICE_NAME: "arcade-worker", "environment": self.environment}
-            )
-
-            self._init_tracer()
-            self._init_metrics()
-            self._init_logging(self.log_level)
-            FastAPIInstrumentor().instrument_app(app)
-
-    def _init_tracer(self) -> None:
-        self._tracer_provider = TracerProvider(resource=self.resource)
-        trace.set_tracer_provider(self._tracer_provider)
-
-        # Create an OTLP exporter
-        self._tracer_span_exporter = OTLPSpanExporter()
-
-        try:
-            self._tracer_span_exporter.export([trace.get_tracer(__name__).start_span("ping")])
-        except Exception as e:
-            raise ConnectionError(
-                f"Could not connect to OpenTelemetry Tracer endpoint. Check OpenTelemetry configuration or disable: {e}"
-            )
-
-        # Create a batch span processor and add the exporter
-        span_processor = BatchSpanProcessor(self._tracer_span_exporter)
-        self._tracer_provider.add_span_processor(span_processor)
-
-    def _init_metrics(self) -> None:
-        self._otlp_metric_exporter = OTLPMetricExporter()
-
-        self._meter_reader = PeriodicExportingMetricReader(self._otlp_metric_exporter)
-
-        self._meter_provider = MeterProvider(
-            metric_readers=[self._meter_reader], resource=self.resource
-        )
-
-        set_meter_provider(self._meter_provider)
-
-    def get_meter(self) -> Meter:
-        return get_meter_provider().get_meter(__name__)
-
-    def _init_logging(self, log_level: int) -> None:
-        otlp_log_exporter = OTLPLogExporter()
-
-        self._logger_provider = LoggerProvider(resource=self.resource)
-        _logs.set_logger_provider(self._logger_provider)
-
-        # Create a batch span processor and add the exporter
-        self._log_processor = BatchLogRecordProcessor(otlp_log_exporter)
-        self._logger_provider.add_log_record_processor(self._log_processor)
-
-        handler = LoggingHandler(level=log_level, logger_provider=self._logger_provider)
-        logging.getLogger().addHandler(handler)
-
-        # Create a filter for urllib3 connection logs related to OpenTelemetry
-        class OTELConnectionFilter(logging.Filter):
-            def filter(self, record: logging.LogRecord) -> bool:
-                # Filter out connection logs to OpenTelemetry endpoints
-                parsed_url = urllib.parse.urlparse(
-                    os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "")
-                )
-                domain = parsed_url.netloc.split(":")[0]
-                return not (domain and domain in str(getattr(record, "args", ())))
-
-        # Apply the filter to the urllib3 logger
-        urllib3_logger = logging.getLogger("urllib3.connectionpool")
-        urllib3_logger.addFilter(OTELConnectionFilter())
-
-    def _shutdown_tracer(self) -> None:
-        if self._tracer_span_exporter is None:
-            raise ShutdownError("Tracer provider not initialized. Failed to shutdown")
-        self._tracer_span_exporter.shutdown()
-
-    def _shutdown_metrics(self) -> None:
-        if self._otlp_metric_exporter is None:
-            raise ShutdownError("Meter provider not initialized. Failed to shutdown")
-        self._otlp_metric_exporter.shutdown()
-
-    def _shutdown_logging(self) -> None:
-        if self._logger_provider is None:
-            raise ShutdownError("Log provider not initialized. Failed to shutdown")
-        self._logger_provider.shutdown()
-
-    def shutdown(self) -> None:
-        self._shutdown_tracer()
-        self._shutdown_metrics()
-        self._shutdown_logging()