xpander-sdk 2.0.179__py3-none-any.whl → 2.0.180__py3-none-any.whl

xpander_sdk/__init__.py

@@ -28,6 +28,7 @@ from .modules.tasks.tasks_module import Tasks, Task, TasksListItem, AgentExecuti
 from xpander_sdk.modules.events.decorators.on_task import on_task
 from xpander_sdk.modules.events.decorators.on_boot import on_boot
 from xpander_sdk.modules.events.decorators.on_shutdown import on_shutdown
+from xpander_sdk.modules.events.decorators.on_tool import on_tool_before, on_tool_after, on_tool_error
 
 # Tools and repository imports
 from .modules.tools_repository.tools_repository_module import ToolsRepository, Tool
@@ -77,6 +78,9 @@ __all__ = [
     "MCPServerAuthType",
     "register_tool",
     "build_model_from_schema",
+    "on_tool_before",
+    "on_tool_after",
+    "on_tool_error",
     # Knowledge bases
     "KnowledgeBases",
     "KnowledgeBase",

xpander_sdk/modules/events/decorators/__init__.py

@@ -0,0 +1,3 @@
+from .on_tool import on_tool_before, on_tool_after, on_tool_error
+
+__all__ = ["on_tool_before", "on_tool_after", "on_tool_error"]

xpander_sdk/modules/events/decorators/on_tool.py

@@ -0,0 +1,384 @@
+"""
+xpander_sdk.decorators.on_tool
+
+This module provides decorators for tool invocation lifecycle hooks:
+- `@on_tool_before`: Execute before tool invocation
+- `@on_tool_after`: Execute after successful tool invocation
+- `@on_tool_error`: Execute when tool invocation fails
+
+The decorators ensure that registered functions:
+- Accept parameters: Tool, payload, payload_extension, tool_call_id, agent_version
+- Can be either synchronous or asynchronous
+- Are called at the appropriate lifecycle stage during tool execution
+
+Execution Notes:
+- Before-hooks execute before tool invocation and can perform validation or logging
+- After-hooks execute after successful invocation with access to the result
+- Error-hooks execute when an exception occurs during invocation
+- Multiple hooks of the same type can be registered and will execute in registration order
+- Exceptions in hooks are logged but don't prevent tool execution
+
+Example usage:
+--------------
+>>> @on_tool_before
+... async def log_tool_invocation(tool, payload, payload_extension, tool_call_id, agent_version):
+...     logger.info(f"Invoking tool {tool.name} with payload: {payload}")
+
+>>> @on_tool_after
+... def record_tool_result(tool, payload, payload_extension, tool_call_id, agent_version, result):
+...     logger.info(f"Tool {tool.name} completed with result: {result}")
+
+>>> @on_tool_error
+... async def handle_tool_error(tool, payload, payload_extension, tool_call_id, agent_version, error):
+...     logger.error(f"Tool {tool.name} failed: {error}")
+"""
+
+import asyncio
+from functools import wraps
+from inspect import iscoroutinefunction
+from typing import Optional, Callable, Any, Dict, List
+
+from xpander_sdk.models.configuration import Configuration
+
+
+class ToolHooksRegistry:
+    """
+    Registry for tool invocation lifecycle hooks.
+    
+    This class maintains class-level lists of hooks that are executed at different
+    stages of tool invocation: before, after, and on error.
+    """
+    
+    _before_hooks: List[Callable] = []
+    _after_hooks: List[Callable] = []
+    _error_hooks: List[Callable] = []
+    
+    @classmethod
+    def register_before_hook(cls, hook: Callable) -> None:
+        """
+        Register a before-invocation hook.
+        
+        Args:
+            hook (Callable): The hook function to execute before tool invocation.
+        """
+        cls._before_hooks.append(hook)
+    
+    @classmethod
+    def register_after_hook(cls, hook: Callable) -> None:
+        """
+        Register an after-invocation hook.
+        
+        Args:
+            hook (Callable): The hook function to execute after successful tool invocation.
+        """
+        cls._after_hooks.append(hook)
+    
+    @classmethod
+    def register_error_hook(cls, hook: Callable) -> None:
+        """
+        Register an error hook.
+        
+        Args:
+            hook (Callable): The hook function to execute when tool invocation fails.
+        """
+        cls._error_hooks.append(hook)
+    
+    @classmethod
+    async def execute_before_hooks(
+        cls,
+        tool: Any,
+        payload: Any,
+        payload_extension: Optional[Dict[str, Any]] = None,
+        tool_call_id: Optional[str] = None,
+        agent_version: Optional[str] = None
+    ) -> None:
+        """
+        Execute all registered before-invocation hooks.
+        
+        Args:
+            tool: The Tool object being invoked.
+            payload: The payload being sent to the tool.
+            payload_extension: Additional payload data.
+            tool_call_id: Unique ID of the tool call.
+            agent_version: Version of the agent making the call.
+        """
+        from loguru import logger
+        
+        for hook in cls._before_hooks:
+            try:
+                if asyncio.iscoroutinefunction(hook):
+                    await hook(tool, payload, payload_extension, tool_call_id, agent_version)
+                else:
+                    hook(tool, payload, payload_extension, tool_call_id, agent_version)
+            except Exception as e:
+                logger.error(f"Before-hook {hook.__name__} failed: {e}")
+    
+    @classmethod
+    async def execute_after_hooks(
+        cls,
+        tool: Any,
+        payload: Any,
+        payload_extension: Optional[Dict[str, Any]] = None,
+        tool_call_id: Optional[str] = None,
+        agent_version: Optional[str] = None,
+        result: Any = None
+    ) -> None:
+        """
+        Execute all registered after-invocation hooks.
+        
+        Args:
+            tool: The Tool object that was invoked.
+            payload: The payload sent to the tool.
+            payload_extension: Additional payload data.
+            tool_call_id: Unique ID of the tool call.
+            agent_version: Version of the agent that made the call.
+            result: The result returned by the tool invocation.
+        """
+        from loguru import logger
+        
+        for hook in cls._after_hooks:
+            try:
+                if asyncio.iscoroutinefunction(hook):
+                    await hook(tool, payload, payload_extension, tool_call_id, agent_version, result)
+                else:
+                    hook(tool, payload, payload_extension, tool_call_id, agent_version, result)
+            except Exception as e:
+                logger.error(f"After-hook {hook.__name__} failed: {e}")
+    
+    @classmethod
+    async def execute_error_hooks(
+        cls,
+        tool: Any,
+        payload: Any,
+        payload_extension: Optional[Dict[str, Any]] = None,
+        tool_call_id: Optional[str] = None,
+        agent_version: Optional[str] = None,
+        error: Optional[Exception] = None
+    ) -> None:
+        """
+        Execute all registered error hooks.
+        
+        Args:
+            tool: The Tool object that failed.
+            payload: The payload sent to the tool.
+            payload_extension: Additional payload data.
+            tool_call_id: Unique ID of the tool call.
+            agent_version: Version of the agent that made the call.
+            error: The exception that occurred during invocation.
+        """
+        from loguru import logger
+        
+        for hook in cls._error_hooks:
+            try:
+                if asyncio.iscoroutinefunction(hook):
+                    await hook(tool, payload, payload_extension, tool_call_id, agent_version, error)
+                else:
+                    hook(tool, payload, payload_extension, tool_call_id, agent_version, error)
+            except Exception as e:
+                logger.error(f"Error-hook {hook.__name__} failed: {e}")
+
+
+def on_tool_before(
+    _func: Optional[Callable] = None,
+    *,
+    configuration: Optional[Configuration] = None
+):
+    """
+    Decorator to register a handler as a before-invocation hook for tool calls.
+    
+    The decorated function will be executed before any tool invocation. The function:
+    - Must accept parameters: tool, payload, payload_extension, tool_call_id, agent_version
+    - Can be either synchronous or asynchronous
+    - Can perform validation, logging, or modification of invocation context
+    
+    Args:
+        _func (Optional[Callable]):
+            The function to decorate (for direct usage like `@on_tool_before`).
+        configuration (Optional[Configuration]):
+            An optional configuration object (reserved for future use).
+    
+    Example:
+        >>> from typing import Optional, Dict, Any
+        >>> from xpander_sdk import Tool
+        >>> 
+        >>> @on_tool_before
+        ... async def validate_tool_input(
+        ...     tool: Tool,
+        ...     payload: Any,
+        ...     payload_extension: Optional[Dict[str, Any]] = None,
+        ...     tool_call_id: Optional[str] = None,
+        ...     agent_version: Optional[str] = None
+        ... ):
+        ...     logger.info(f"Pre-invoking tool: {tool.name}")
+        ...     if not payload:
+        ...         logger.warning("Empty payload provided")
+        
+        >>> @on_tool_before
+        ... def log_tool_metrics(
+        ...     tool: Tool,
+        ...     payload: Any,
+        ...     payload_extension: Optional[Dict[str, Any]] = None,
+        ...     tool_call_id: Optional[str] = None,
+        ...     agent_version: Optional[str] = None
+        ... ):
+        ...     metrics.record_tool_invocation(tool.name, tool_call_id)
+    """
+    
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            return await func(*args, **kwargs)
+        
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+        
+        wrapped = async_wrapper if iscoroutinefunction(func) else sync_wrapper
+        
+        # Register hook in the registry
+        ToolHooksRegistry.register_before_hook(wrapped)
+        
+        return wrapped
+    
+    if _func and callable(_func):
+        return decorator(_func)
+    
+    return decorator
+
+
+def on_tool_after(
+    _func: Optional[Callable] = None,
+    *,
+    configuration: Optional[Configuration] = None
+):
+    """
+    Decorator to register a handler as an after-invocation hook for tool calls.
+    
+    The decorated function will be executed after successful tool invocation. The function:
+    - Must accept parameters: tool, payload, payload_extension, tool_call_id, agent_version, result
+    - Can be either synchronous or asynchronous
+    - Can perform logging, analytics, or result processing
+    
+    Args:
+        _func (Optional[Callable]):
+            The function to decorate (for direct usage like `@on_tool_after`).
+        configuration (Optional[Configuration]):
+            An optional configuration object (reserved for future use).
+    
+    Example:
+        >>> from typing import Optional, Dict, Any
+        >>> from xpander_sdk import Tool
+        >>> 
+        >>> @on_tool_after
+        ... async def log_tool_success(
+        ...     tool: Tool,
+        ...     payload: Any,
+        ...     payload_extension: Optional[Dict[str, Any]] = None,
+        ...     tool_call_id: Optional[str] = None,
+        ...     agent_version: Optional[str] = None,
+        ...     result: Any = None
+        ... ):
+        ...     logger.info(f"Tool {tool.name} succeeded with result: {result}")
+        ...     analytics.record_success(tool.name, tool_call_id)
+        
+        >>> @on_tool_after
+        ... def cache_tool_result(
+        ...     tool: Tool,
+        ...     payload: Any,
+        ...     payload_extension: Optional[Dict[str, Any]] = None,
+        ...     tool_call_id: Optional[str] = None,
+        ...     agent_version: Optional[str] = None,
+        ...     result: Any = None
+        ... ):
+        ...     cache.set(f"tool_{tool.id}_{hash(payload)}", result)
+    """
+    
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            return await func(*args, **kwargs)
+        
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+        
+        wrapped = async_wrapper if iscoroutinefunction(func) else sync_wrapper
+        
+        # Register hook in the registry
+        ToolHooksRegistry.register_after_hook(wrapped)
+        
+        return wrapped
+    
+    if _func and callable(_func):
+        return decorator(_func)
+    
+    return decorator
+
+
+def on_tool_error(
+    _func: Optional[Callable] = None,
+    *,
+    configuration: Optional[Configuration] = None
+):
+    """
+    Decorator to register a handler as an error hook for tool calls.
+    
+    The decorated function will be executed when tool invocation fails. The function:
+    - Must accept parameters: tool, payload, payload_extension, tool_call_id, agent_version, error
+    - Can be either synchronous or asynchronous
+    - Can perform error logging, alerting, or recovery actions
+    
+    Args:
+        _func (Optional[Callable]):
+            The function to decorate (for direct usage like `@on_tool_error`).
+        configuration (Optional[Configuration]):
+            An optional configuration object (reserved for future use).
+    
+    Example:
+        >>> from typing import Optional, Dict, Any
+        >>> from xpander_sdk import Tool
+        >>> 
+        >>> @on_tool_error
+        ... async def alert_on_tool_failure(
+        ...     tool: Tool,
+        ...     payload: Any,
+        ...     payload_extension: Optional[Dict[str, Any]] = None,
+        ...     tool_call_id: Optional[str] = None,
+        ...     agent_version: Optional[str] = None,
+        ...     error: Optional[Exception] = None
+        ... ):
+        ...     logger.error(f"Tool {tool.name} failed: {error}")
+        ...     await send_alert(f"Tool failure: {tool.name}", str(error))
+        
+        >>> @on_tool_error
+        ... def log_tool_failure(
+        ...     tool: Tool,
+        ...     payload: Any,
+        ...     payload_extension: Optional[Dict[str, Any]] = None,
+        ...     tool_call_id: Optional[str] = None,
+        ...     agent_version: Optional[str] = None,
+        ...     error: Optional[Exception] = None
+        ... ):
+        ...     error_log.write(f"{tool.name},{tool_call_id},{str(error)}\n")
+    """
+    
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            return await func(*args, **kwargs)
+        
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+        
+        wrapped = async_wrapper if iscoroutinefunction(func) else sync_wrapper
+        
+        # Register hook in the registry
+        ToolHooksRegistry.register_error_hook(wrapped)
+        
+        return wrapped
+    
+    if _func and callable(_func):
+        return decorator(_func)
+    
+    return decorator

xpander_sdk/modules/tools_repository/sub_modules/tool.py

@@ -41,6 +41,7 @@ from xpander_sdk.modules.tools_repository.utils.schemas import (
     schema_enforcement_block_and_descriptions,
 )
 from xpander_sdk.utils.event_loop import run_sync
+from xpander_sdk.modules.events.decorators.on_tool import ToolHooksRegistry
 
 
 class Tool(XPanderSharedModel):
@@ -376,6 +377,15 @@ class Tool(XPanderSharedModel):
             task_id=task_id,
         )
 
+        # Execute before hooks
+        await ToolHooksRegistry.execute_before_hooks(
+            tool=self,
+            payload=payload,
+            payload_extension=payload_extension,
+            tool_call_id=tool_call_id,
+            agent_version=agent_version
+        )
+
         try:
             if self.schema and payload:
                 try:
@@ -403,17 +413,26 @@ class Tool(XPanderSharedModel):
                 
                 tool_invocation_result.result = result
                 tool_invocation_result.is_success = True
-                return tool_invocation_result
-
-            tool_invocation_result.result = await self.acall_remote_tool(
-                agent_id=agent_id,
-                agent_version=agent_version,
+            else:
+                tool_invocation_result.result = await self.acall_remote_tool(
+                    agent_id=agent_id,
+                    agent_version=agent_version,
+                    payload=payload,
+                    payload_extension=payload_extension,
+                    configuration=configuration,
+                    task_id=task_id,
+                )
+                tool_invocation_result.is_success = True
+            
+            # Execute after hooks on success
+            await ToolHooksRegistry.execute_after_hooks(
+                tool=self,
                 payload=payload,
                 payload_extension=payload_extension,
-                configuration=configuration,
-                task_id=task_id,
+                tool_call_id=tool_call_id,
+                agent_version=agent_version,
+                result=tool_invocation_result.result
             )
-            tool_invocation_result.is_success = True
 
         except Exception as e:
             tool_invocation_result.is_error = True
@@ -423,6 +442,16 @@ class Tool(XPanderSharedModel):
             else:
                 tool_invocation_result.status_code = 500
                 tool_invocation_result.result = str(e)
+            
+            # Execute error hooks on failure
+            await ToolHooksRegistry.execute_error_hooks(
+                tool=self,
+                payload=payload,
+                payload_extension=payload_extension,
+                tool_call_id=tool_call_id,
+                agent_version=agent_version,
+                error=e
+            )
 
         return tool_invocation_result
 

{xpander_sdk-2.0.179.dist-info → xpander_sdk-2.0.180.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.179
+Version: 2.0.180
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.179.dist-info → xpander_sdk-2.0.180.dist-info}/RECORD

@@ -1,4 +1,4 @@
-xpander_sdk/__init__.py,sha256=ETLxETELJT1j5Q4xL7sWC-Kz4FRps8IvLoYexNCDqcs,2760
+xpander_sdk/__init__.py,sha256=34l3YcvIdkj81DTfMp_bgZgXpj2U1lTKpHQ0shwnc_8,2927
 xpander_sdk/consts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/consts/api_routes.py,sha256=dKUruLanvprTxZO15fR4OWe6ck8JQ8y64XmUJxsbeJY,2278
 xpander_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -39,10 +39,11 @@ xpander_sdk/modules/backend/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeR
 xpander_sdk/modules/backend/utils/mcp_oauth.py,sha256=K80bLjFW66TXm-wz5mbtZEeKjpeYr6ezhMFb5r3bhXA,5468
 xpander_sdk/modules/events/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/events/events_module.py,sha256=DVlho7JxT6Jy8GeyuSakswmYwR18xqO2JcCJ-8Zc3s8,25317
-xpander_sdk/modules/events/decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xpander_sdk/modules/events/decorators/__init__.py,sha256=8GhR9afoLiS83a0OMLpn7TN2W6iTnlcVqos6bM34nac,129
 xpander_sdk/modules/events/decorators/on_boot.py,sha256=VGtoQcgs3g5bmx3Ze4QB_-ZwBESATYYVR0oZe35eCww,3076
 xpander_sdk/modules/events/decorators/on_shutdown.py,sha256=rFgChspnLDnZm9FS1K636dvZSQDkeugf2e3M83SDgAY,3127
 xpander_sdk/modules/events/decorators/on_task.py,sha256=G3jk0xzi3pqH96Bbut_GMJKExIlyyMYk4PbKfc6koa4,8551
+xpander_sdk/modules/events/decorators/on_tool.py,sha256=ZacZ6tADjvl79ISqKxTSH1P0nZUS8C3mRwOL2SyLeZE,13750
 xpander_sdk/modules/events/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/events/models/deployments.py,sha256=6uwxFsybrZ-eHeohJzkm2RtQq4Eo_0xjHk7QouvszxU,1335
 xpander_sdk/modules/events/models/events.py,sha256=T_89pq48e7fMIbJcCbtM9Ocb6YKXQP7pbF6VbECiGcI,1550
@@ -74,7 +75,7 @@ xpander_sdk/modules/tools_repository/models/__init__.py,sha256=47DEQpj8HBSa-_TIm
 xpander_sdk/modules/tools_repository/models/mcp.py,sha256=qGpaiXKiuXw6gAcK8CW6ek6FkZNbBxDXUf1PWF6Tenw,1863
 xpander_sdk/modules/tools_repository/models/tool_invocation_result.py,sha256=Dhowt_fv8v8xWv7xMRJxo6hA8DawXKbWIrsJFMpt5H4,447
 xpander_sdk/modules/tools_repository/sub_modules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/tools_repository/sub_modules/tool.py,sha256=ylSVfekQQd0vPCKXPWN67tlkyVT7R4WsSQtoEZcBETw,22521
+xpander_sdk/modules/tools_repository/sub_modules/tool.py,sha256=rivnznxi6CrrOWE1rukkBRmad2H-rthhrelC7ei1IXM,23617
 xpander_sdk/modules/tools_repository/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/tools_repository/utils/generic.py,sha256=m9FRaVGzRUj23tB52rP9K4O-nTsMSt9iwMxMcYsqfiY,1770
 xpander_sdk/modules/tools_repository/utils/local_tools.py,sha256=zp5P8hVnRUJQb-w-2jCEMV5eUB_awmvYfY_rin5qvEw,1875
@@ -86,8 +87,8 @@ xpander_sdk/utils/generic.py,sha256=XrRj2-L8c0YWpfPdDyXE-pVL-6lKF9VpyZzKHQ4wuCc,
 xpander_sdk/utils/tools.py,sha256=lyFkq2yP7DxBkyXYVlnFRwDhQCvf0fZZMDm5fBycze4,1244
 xpander_sdk/utils/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/utils/agents/compactization_agent.py,sha256=pqaf7LVSyPFaeXU62dMPY6iQ160TFga1KJ0Kgu1dIgg,14449
-xpander_sdk-2.0.179.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-xpander_sdk-2.0.179.dist-info/METADATA,sha256=6dcIt4ajwKjEFSmOUqg8MgzDwe7hXeEnckKXKAnxohc,17880
-xpander_sdk-2.0.179.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-xpander_sdk-2.0.179.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
-xpander_sdk-2.0.179.dist-info/RECORD,,
+xpander_sdk-2.0.180.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+xpander_sdk-2.0.180.dist-info/METADATA,sha256=NfaTIonGkunIZxzmX3C82qiGcKeewspcwnJhHcqIYOM,17880
+xpander_sdk-2.0.180.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xpander_sdk-2.0.180.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
+xpander_sdk-2.0.180.dist-info/RECORD,,