xpander-sdk 1.60.4__py3-none-any.whl → 2.0.155__py3-none-any.whl

xpander_sdk/modules/tools_repository/decorators/register_tool.py

@@ -0,0 +1,108 @@
+"""
+Decorator for registering local tools in the xpander.ai SDK.
+
+This module provides the @register_tool decorator that allows developers to
+register Python functions as tools that can be used by AI agents in the
+xpander.ai platform.
+"""
+
+import inspect
+from typing import Callable, Any, Optional, get_type_hints, Union
+from pydantic import create_model
+from xpander_sdk.modules.tools_repository.sub_modules.tool import Tool
+from xpander_sdk.modules.tools_repository.tools_repository_module import ToolsRepository
+
+
+def register_tool(
+    func: Optional[Callable] = None, 
+    *, 
+    add_to_graph: Optional[bool] = False
+) -> Union[Callable, Tool]:
+    """
+    Decorator to register a Python function as a tool for xpander.ai agents.
+    
+    This decorator automatically creates a Tool object from a Python function,
+    extracting type hints and docstrings to generate a proper tool schema that
+    can be used by AI agents. The decorated function becomes available in the
+    tools repository and can optionally be added to agent execution graphs.
+    
+    Args:
+        func (Optional[Callable]): The function to register (used for @register_tool syntax).
+        add_to_graph (Optional[bool]): Whether to automatically add this tool to
+            agent execution graphs. Defaults to False.
+            
+    Returns:
+        Union[Callable, Tool]: The original function (preserves functionality) or
+            a partial decorator when used with arguments.
+            
+    Raises:
+        TypeError: If the decorated object is not a callable function.
+        
+    Example:
+        >>> @register_tool
+        ... def calculate_sum(a: int, b: int) -> int:
+        ...     return a + b
+        
+        >>> @register_tool(add_to_graph=True)
+        ... def fetch_weather(city: str, country: str = "US") -> str:
+        ...     # Implementation here
+        ...     return f"Weather for {city}, {country}"
+        
+        >>> # The functions remain callable as normal
+        >>> result = calculate_sum(5, 3)  # Returns 8
+        
+        >>> # But are also available as tools
+        >>> tools = ToolsRepository()
+        >>> tool = tools.get_tool_by_id("calculate_sum")
+    """
+    
+    def decorator(inner_func: Callable) -> Callable:
+        """
+        Inner decorator that processes the function and creates a tool.
+        
+        Args:
+            inner_func (Callable): The function to be registered as a tool.
+            
+        Returns:
+            Callable: The original function, unchanged in functionality.
+        """
+        # Extract function signature and type hints
+        sig = inspect.signature(inner_func)
+        hints = get_type_hints(inner_func)
+
+        # Build Pydantic model for function arguments
+        fields = {}
+        for name, param in sig.parameters.items():
+            annotation = hints.get(name, Any)
+            default = param.default if param.default is not inspect.Parameter.empty else ...
+            fields[name] = (annotation, default)
+
+        # Create a Pydantic model class for argument validation
+        ArgsModel = create_model(f"{inner_func.__name__.title()}Args", **fields)  # type: ignore
+
+        # Create Tool object with extracted metadata
+        tool = Tool(
+            id=inner_func.__name__,
+            name=inner_func.__name__,
+            method="POST",
+            path=f"/tools/{inner_func.__name__}",
+            description=inspect.getdoc(inner_func) or "",
+            parameters=ArgsModel.model_json_schema(mode="serialization"),
+            fn=inner_func,
+            is_local=True,
+            should_add_to_graph=add_to_graph
+        )
+
+        # Register the tool in the global repository
+        ToolsRepository.register_tool(tool)
+        
+        # Return the original function unchanged
+        return inner_func
+
+    # Handle both @register_tool and @register_tool(...) syntax
+    if func is None:
+        # Called with arguments: @register_tool(add_to_graph=True)
+        return decorator
+    else:
+        # Called without parentheses: @register_tool
+        return decorator(func)

xpander_sdk/modules/tools_repository/models/mcp.py

@@ -0,0 +1,68 @@
+from enum import Enum
+from typing import Dict, List, Optional, Union
+
+from pydantic import BaseModel
+
+from xpander_sdk.models.shared import XPanderSharedModel
+
+
+class MCPServerType(str, Enum):
+    Local = "local"
+    Remote = "remote"
+    
+class MCPServerAuthType(str, Enum):
+    APIKey = "api_key"
+    OAuth2 = "oauth2"
+    CustomHeaders = "custom_headers"
+    _None = "none"
+
+class MCPServerTransport(str, Enum):
+    STDIO = "stdio"
+    SSE = "sse"
+    HTTP_Transport = "streamable-http"
+
+class MCPServerDetails(BaseModel):
+    type: Optional[MCPServerType] = MCPServerType.Remote
+    name: Optional[str] = None
+    command: Optional[str] = None
+    url: Optional[str] = None
+    transport: Optional[MCPServerTransport] = MCPServerTransport.HTTP_Transport
+    auth_type: Optional[MCPServerAuthType] = MCPServerAuthType._None
+    api_key: Optional[str] = None
+    client_id: Optional[str] = None
+    client_secret: Optional[str] = None
+    headers: Optional[Dict] = {}
+    env_vars: Optional[Dict] = {}
+    allowed_tools: Optional[List[str]] = []
+    additional_scopes: Optional[List[str]] = []
+    share_user_token_across_other_agents: Optional[bool] = True
+
+
+class MCPOAuthResponseType(str, Enum):
+    NOT_SUPPORTED = "not_supported"
+    LOGIN_REQUIRED = "login_required"
+    TOKEN_ISSUE = "token_issue"
+    TOKEN_READY = "token_ready"
+
+
+class MCPOAuthGetTokenGenericResponse(XPanderSharedModel):
+    message: str
+
+
+class MCPOAuthGetTokenLoginRequiredResponse(XPanderSharedModel):
+    url: str
+    server_url: str
+    server_name: str
+
+
+class MCPOAuthGetTokenTokenReadyResponse(XPanderSharedModel):
+    access_token: str
+
+
+class MCPOAuthGetTokenResponse(XPanderSharedModel):
+    type: MCPOAuthResponseType
+    data: Union[
+        MCPOAuthGetTokenTokenReadyResponse,
+        MCPOAuthGetTokenLoginRequiredResponse,
+        MCPOAuthGetTokenGenericResponse,
+    ]

xpander_sdk/modules/tools_repository/models/tool_invocation_result.py

@@ -0,0 +1,14 @@
+from typing import Any, Optional
+from xpander_sdk.models.shared import XPanderSharedModel
+
+
+class ToolInvocationResult(XPanderSharedModel):
+    tool_id: str
+    tool_call_id: Optional[str] = None
+    task_id: Optional[str] = None
+    payload: Optional[Any] = None
+    status_code: Optional[int] = 200
+    result: Optional[Any] = None
+    is_success: Optional[bool] = False
+    is_error: Optional[bool] = False
+    is_local: Optional[bool] = False