xpander-sdk 2.0.178__tar.gz → 2.0.180__tar.gz

{xpander_sdk-2.0.178 → xpander_sdk-2.0.180}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.178
+Version: 2.0.180
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI
@@ -293,6 +293,89 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Authentication Events Callback
+
+Handle authentication events in real-time. This callback is triggered only for authentication flows (e.g., MCP OAuth requiring user login).
+
+**You can use both approaches simultaneously** - decorated handlers will always be invoked, and you can also pass an explicit callback for additional handling.
+
+You can provide the callback in two ways:
+
+#### Option 1: Direct Function
+
+```python
+from xpander_sdk import Backend
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Define event callback (async or sync)
+async def my_event_callback(agent: Agent, task: Task, event: TaskUpdateEvent):
+    """Called for authentication events only"""
+    # event.type will always be "auth_event"
+    print(f"Authentication required: {event.data}")
+    # Display login URL or handle OAuth flow
+
+# Get args with callback
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task,
+    auth_events_callback=my_event_callback
+)
+```
+
+#### Option 2: Decorator (Auto-registered)
+
+```python
+from xpander_sdk import Backend, on_auth_event
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Use decorator - auto-registers globally
+@on_auth_event
+async def handle_auth(agent: Agent, task: Task, event: TaskUpdateEvent):
+    # event.type will always be "auth_event"
+    print(f"Authentication required for {agent.name}")
+    print(f"Auth data: {event.data}")
+
+# Decorated handler is automatically invoked - no need to pass it
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task
+)
+```
+
+#### Option 3: Combine Both
+
+```python
+from xpander_sdk import Backend, on_auth_event
+
+# Global handler for all auth events
+@on_auth_event
+async def log_auth(agent, task, event):
+    print(f"[GLOBAL] Auth event for {agent.name}")
+
+# Additional one-time handler
+async def custom_handler(agent, task, event):
+    print(f"[CUSTOM] Specific handling for this call")
+
+# Both handlers will be invoked
+args = await backend.aget_args(
+    agent_id="agent-123",
+    auth_events_callback=custom_handler  # Optional additional callback
+)
+
+# Use with Agno
+agno_agent = AgnoAgent(**args)
+result = await agno_agent.arun(
+    input="Process this data",
+    stream=True
+)
+```
+
 ### Task Activity Monitoring
 
 ```python

{xpander_sdk-2.0.178 → xpander_sdk-2.0.180}/README.md

@@ -243,6 +243,89 @@ async for event in task.aevents():
     print(f"Event Data: {event.data}")
 ```
 
+### Authentication Events Callback
+
+Handle authentication events in real-time. This callback is triggered only for authentication flows (e.g., MCP OAuth requiring user login).
+
+**You can use both approaches simultaneously** - decorated handlers will always be invoked, and you can also pass an explicit callback for additional handling.
+
+You can provide the callback in two ways:
+
+#### Option 1: Direct Function
+
+```python
+from xpander_sdk import Backend
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Define event callback (async or sync)
+async def my_event_callback(agent: Agent, task: Task, event: TaskUpdateEvent):
+    """Called for authentication events only"""
+    # event.type will always be "auth_event"
+    print(f"Authentication required: {event.data}")
+    # Display login URL or handle OAuth flow
+
+# Get args with callback
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task,
+    auth_events_callback=my_event_callback
+)
+```
+
+#### Option 2: Decorator (Auto-registered)
+
+```python
+from xpander_sdk import Backend, on_auth_event
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from agno.agent import Agent as AgnoAgent
+
+# Use decorator - auto-registers globally
+@on_auth_event
+async def handle_auth(agent: Agent, task: Task, event: TaskUpdateEvent):
+    # event.type will always be "auth_event"
+    print(f"Authentication required for {agent.name}")
+    print(f"Auth data: {event.data}")
+
+# Decorated handler is automatically invoked - no need to pass it
+backend = Backend(configuration=config)
+args = await backend.aget_args(
+    agent_id="agent-123",
+    task=my_task
+)
+```
+
+#### Option 3: Combine Both
+
+```python
+from xpander_sdk import Backend, on_auth_event
+
+# Global handler for all auth events
+@on_auth_event
+async def log_auth(agent, task, event):
+    print(f"[GLOBAL] Auth event for {agent.name}")
+
+# Additional one-time handler
+async def custom_handler(agent, task, event):
+    print(f"[CUSTOM] Specific handling for this call")
+
+# Both handlers will be invoked
+args = await backend.aget_args(
+    agent_id="agent-123",
+    auth_events_callback=custom_handler  # Optional additional callback
+)
+
+# Use with Agno
+agno_agent = AgnoAgent(**args)
+result = await agno_agent.arun(
+    input="Process this data",
+    stream=True
+)
+```
+
 ### Task Activity Monitoring
 
 ```python

{xpander_sdk-2.0.178 → xpander_sdk-2.0.180}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.178",
+    version="2.0.180",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

{xpander_sdk-2.0.178 → xpander_sdk-2.0.180}/src/xpander_sdk/__init__.py

@@ -17,6 +17,7 @@ For more information, visit: https://xpander.ai
 
 # Backend-related imports
 from .modules.backend.backend_module import Backend
+from .modules.backend.decorators.on_auth_event import on_auth_event
 
 # Agent-related imports
 from .modules.agents.agents_module import Agents, Agent, AgentsListItem
@@ -27,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
@@ -53,6 +55,7 @@ from .models.shared import OutputFormat, Tokens
 __all__ = [
     # xpander.ai Backend
     "Backend",
+    "on_auth_event",
     # Agent management
     "Agents",
     "Agent",
@@ -75,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-2.0.180/src/xpander_sdk/modules/backend/__init__.py

@@ -0,0 +1,8 @@
+"""
+Backend module for xpander.ai SDK.
+"""
+
+from .backend_module import Backend
+from .decorators.on_auth_event import on_auth_event
+
+__all__ = ["Backend", "on_auth_event"]

{xpander_sdk-2.0.178 → xpander_sdk-2.0.180}/src/xpander_sdk/modules/backend/backend_module.py

@@ -231,6 +231,7 @@ class Backend(ModuleBase):
         override: Optional[Dict[str, Any]] = None,
         tools: Optional[List[Callable]] = None,
         is_async: Optional[bool] = True,
+        auth_events_callback: Optional[Callable] = None,
     ) -> Dict[str, Any]:
         """
         Asynchronously resolve runtime arguments for the specified agent.
@@ -243,6 +244,27 @@ class Backend(ModuleBase):
             override (Optional[Dict[str, Any]]): Optional overrides for final arguments.
             tools (Optional[List[Callable]]): Optional additional tools to be added to the agent arguments.
             is_async (Optional[bool]): Is in Async Context?.
+            auth_events_callback (Optional[Callable]): Optional callback function (async or sync) that will be called for authentication events only.
+                Used specifically for authentication events (e.g., MCP OAuth flows requiring user login).
+                The callback signature must be: callback(agent: Agent, task: Task, event: TaskUpdateEvent)
+                
+                Can be provided in two ways:
+                1. Direct function: Pass the function directly to this parameter
+                2. Decorator: Use @on_auth_event decorator and pass the decorated function
+                
+                Example (direct function):
+                    async def my_callback(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    args = await backend.aget_args(agent_id="...", auth_events_callback=my_callback)
+                
+                Example (decorator):
+                    from xpander_sdk import on_auth_event
+                    
+                    @on_auth_event
+                    async def handle_auth(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    
+                    args = await backend.aget_args(agent_id="...", auth_events_callback=handle_auth)
 
         Returns:
             Dict[str, Any]: Resolved argument dictionary to use with the agent.
@@ -267,7 +289,7 @@ class Backend(ModuleBase):
                 "or set via the 'XPANDER_AGENT_ID' environment variable."
             )
 
-        return await dispatch_get_args(agent=xpander_agent, task=task, override=override, tools=tools, is_async=is_async)
+        return await dispatch_get_args(agent=xpander_agent, task=task, override=override, tools=tools, is_async=is_async, auth_events_callback=auth_events_callback)
 
     def get_args(
         self,
@@ -277,6 +299,7 @@ class Backend(ModuleBase):
         task: Optional[Task] = None,
         override: Optional[Dict[str, Any]] = None,
         tools: Optional[List[Callable]] = None,
+        auth_events_callback: Optional[Callable] = None,
     ) -> Dict[str, Any]:
         """
         Synchronously resolve runtime arguments for the specified agent.
@@ -291,6 +314,27 @@ class Backend(ModuleBase):
             task (Optional[Task]): Optional Task object providing runtime input/output context.
             override (Optional[Dict[str, Any]]): Optional overrides for final arguments.
             tools (Optional[List[Callable]]): Optional additional tools to be added to the agent arguments.
+            auth_events_callback (Optional[Callable]): Optional callback function (async or sync) that will be called for authentication events only.
+                Used specifically for authentication events (e.g., MCP OAuth flows requiring user login).
+                The callback signature must be: callback(agent: Agent, task: Task, event: TaskUpdateEvent)
+                
+                Can be provided in two ways:
+                1. Direct function: Pass the function directly to this parameter
+                2. Decorator: Use @on_auth_event decorator and pass the decorated function
+                
+                Example (direct function):
+                    def my_callback(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    args = backend.get_args(agent_id="...", auth_events_callback=my_callback)
+                
+                Example (decorator):
+                    from xpander_sdk import on_auth_event
+                    
+                    @on_auth_event
+                    def handle_auth(agent, task, event):
+                        print(f"Auth required: {event.data}")
+                    
+                    args = backend.get_args(agent_id="...", auth_events_callback=handle_auth)
 
         Returns:
             Dict[str, Any]: Resolved argument dictionary to use with the agent.
@@ -306,7 +350,8 @@ class Backend(ModuleBase):
                 task=task,
                 override=override,
                 tools=tools,
-                is_async=False
+                is_async=False,
+                auth_events_callback=auth_events_callback
             )
         )
     

xpander_sdk-2.0.180/src/xpander_sdk/modules/backend/decorators/__init__.py

@@ -0,0 +1,7 @@
+"""
+Backend module decorators.
+"""
+
+from .on_auth_event import on_auth_event
+
+__all__ = ["on_auth_event"]

xpander_sdk-2.0.180/src/xpander_sdk/modules/backend/decorators/on_auth_event.py

@@ -0,0 +1,131 @@
+"""
+xpander_sdk.modules.backend.decorators.on_auth_event
+
+This module provides the `@on_auth_event` decorator, which allows developers to define
+authentication event handlers that respond to OAuth flows and authentication events.
+
+The decorator ensures that the registered function:
+- Accepts three parameters: agent (Agent), task (Task), and event (TaskUpdateEvent)
+- Handles authentication events (e.g., MCP OAuth flows requiring user login)
+- Can be either synchronous or asynchronous
+
+Execution Notes:
+- The handler is called when authentication events occur (e.g., OAuth login required)
+- The event.type will always be "auth_event"
+- The event.data contains authentication-specific information (e.g., OAuth login URL)
+- Use this for displaying authentication prompts, handling OAuth flows, etc.
+
+Example usage:
+--------------
+>>> from xpander_sdk import Backend, on_auth_event
+>>> 
+>>> # Define handler with decorator - auto-registers globally
+>>> @on_auth_event
+... async def handle_auth(agent, task, event):
+...     print(f"Authentication required for {agent.name}")
+...     print(f"Login URL: {event.data.get('auth_url')}")
+...     # Display authentication prompt to user
+>>> 
+>>> # Handler is automatically invoked when auth events occur
+>>> backend = Backend()
+>>> args = await backend.aget_args(agent_id="agent-123")  # handle_auth is called automatically
+"""
+
+from functools import wraps
+from inspect import iscoroutinefunction, signature
+from typing import Optional, Callable
+
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.modules.tasks.sub_modules.task import Task, TaskUpdateEvent
+from xpander_sdk.modules.backend.events_registry import EventsRegistry, EventType
+
+
+def on_auth_event(_func: Optional[Callable] = None):
+    """
+    Decorator to register a handler for authentication events.
+
+    The decorated function is automatically registered globally and will be called
+    whenever authentication events occur during agent execution (e.g., MCP OAuth flows
+    requiring user login). The function:
+    - Must accept three parameters: agent (Agent), task (Task), event (TaskUpdateEvent)
+    - Can be either synchronous or asynchronous
+    - Receives only authentication events (event.type == "auth_event")
+    - Is invoked automatically - no need to pass it to aget_args/get_args
+
+    Args:
+        _func (Optional[Callable]):
+            The function to decorate (for direct usage like `@on_auth_event`).
+
+    Raises:
+        TypeError: If the decorated function does not have the correct parameters.
+
+    Example:
+        >>> @on_auth_event
+        ... async def handle_oauth_login(agent, task, event):
+        ...     print(f"Agent: {agent.name}")
+        ...     print(f"Task: {task.id}")
+        ...     print(f"Auth data: {event.data}")
+        ...     # Handle OAuth flow
+        
+        >>> @on_auth_event
+        ... def sync_auth_handler(agent, task, event):
+        ...     if 'auth_url' in event.data:
+        ...         print(f"Please visit: {event.data['auth_url']}")
+    """
+
+    def decorator(func: Callable) -> Callable:
+        sig = signature(func)
+        params = list(sig.parameters.keys())
+
+        # Validate function signature
+        if len(params) < 3:
+            raise TypeError(
+                f"Function '{func.__name__}' must accept 3 parameters: agent, task, event. "
+                f"Got {len(params)} parameters: {params}"
+            )
+
+        # Store the original function for later use
+        @wraps(func)
+        async def async_wrapper(agent: Agent, task: Task, event: TaskUpdateEvent):
+            return await func(agent, task, event)
+
+        @wraps(func)
+        def sync_wrapper(agent: Agent, task: Task, event: TaskUpdateEvent):
+            return func(agent, task, event)
+
+        wrapped = async_wrapper if iscoroutinefunction(func) else sync_wrapper
+        
+        # Mark the function as an auth event handler
+        wrapped._is_auth_event_handler = True
+        
+        # Register the handler in the singleton registry
+        registry = EventsRegistry()
+        registry.register_auth_event(wrapped)
+        
+        return wrapped
+
+    if _func and callable(_func):
+        return decorator(_func)
+
+    return decorator
+
+
+def get_registered_handlers():
+    """
+    Get all registered authentication event handlers.
+    
+    Returns:
+        list: List of registered handler functions.
+    """
+    registry = EventsRegistry()
+    return registry.get_auth_handlers()
+
+
+def clear_handlers():
+    """
+    Clear all registered authentication event handlers.
+    
+    Useful for testing or when you want to reset the handlers.
+    """
+    registry = EventsRegistry()
+    registry.clear(EventType.AUTH_EVENT)

xpander_sdk-2.0.180/src/xpander_sdk/modules/backend/events_registry.py

@@ -0,0 +1,172 @@
+"""
+Events Registry - Singleton pattern for managing event handlers and hooks.
+
+This registry supports multiple event types:
+- Authentication events (OAuth flows)
+- Tool call hooks (pre/post/error) - Coming soon
+"""
+
+from typing import Callable, List, Optional, Dict, Any
+from enum import Enum
+import asyncio
+
+
+class EventType(str, Enum):
+    """Supported event types in the backend module."""
+    AUTH_EVENT = "auth_event"
+    TOOL_PRE_CALL = "tool_pre_call"  # Future: before tool execution
+    TOOL_POST_CALL = "tool_post_call"  # Future: after successful tool execution
+    TOOL_ERROR = "tool_error"  # Future: when tool execution fails
+
+
+class EventsRegistry:
+    """
+    Singleton registry for managing event handlers and hooks.
+    
+    This registry maintains handlers for different event types and provides
+    methods to register, retrieve, and invoke them.
+    
+    Supported event types:
+    - AUTH_EVENT: Authentication events (e.g., MCP OAuth flows)
+    - TOOL_PRE_CALL: Before tool execution (future)
+    - TOOL_POST_CALL: After successful tool execution (future)
+    - TOOL_ERROR: When tool execution fails (future)
+    """
+    
+    _instance: Optional['EventsRegistry'] = None
+    _handlers: Dict[EventType, List[Callable]] = {}
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._handlers = {
+                EventType.AUTH_EVENT: [],
+                EventType.TOOL_PRE_CALL: [],
+                EventType.TOOL_POST_CALL: [],
+                EventType.TOOL_ERROR: [],
+            }
+        return cls._instance
+    
+    def register(self, event_type: EventType, handler: Callable) -> None:
+        """
+        Register an event handler for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event to handle.
+            handler (Callable): The handler function to register.
+        """
+        if event_type not in self._handlers:
+            self._handlers[event_type] = []
+        
+        if handler not in self._handlers[event_type]:
+            self._handlers[event_type].append(handler)
+    
+    def register_auth_event(self, handler: Callable) -> None:
+        """
+        Register an authentication event handler.
+        
+        Args:
+            handler (Callable): The handler function to register.
+        """
+        self.register(EventType.AUTH_EVENT, handler)
+    
+    def get_handlers(self, event_type: EventType) -> List[Callable]:
+        """
+        Get all registered handlers for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event.
+        
+        Returns:
+            List[Callable]: List of registered handler functions.
+        """
+        return self._handlers.get(event_type, []).copy()
+    
+    def get_auth_handlers(self) -> List[Callable]:
+        """
+        Get all registered authentication event handlers.
+        
+        Returns:
+            List[Callable]: List of registered auth handler functions.
+        """
+        return self.get_handlers(EventType.AUTH_EVENT)
+    
+    def clear(self, event_type: Optional[EventType] = None) -> None:
+        """
+        Clear registered handlers.
+        
+        Args:
+            event_type (Optional[EventType]): If provided, clear only handlers
+                for this event type. If None, clear all handlers.
+        """
+        if event_type:
+            if event_type in self._handlers:
+                self._handlers[event_type].clear()
+        else:
+            for handlers_list in self._handlers.values():
+                handlers_list.clear()
+    
+    async def invoke_handlers(self, event_type: EventType, *args, **kwargs) -> None:
+        """
+        Invoke all registered handlers for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event to invoke handlers for.
+            *args: Positional arguments to pass to handlers.
+            **kwargs: Keyword arguments to pass to handlers.
+        """
+        handlers = self._handlers.get(event_type, [])
+        
+        for handler in handlers:
+            try:
+                if asyncio.iscoroutinefunction(handler):
+                    await handler(*args, **kwargs)
+                else:
+                    handler(*args, **kwargs)
+            except Exception as e:
+                # Log error but continue with other handlers
+                from loguru import logger
+                logger.error(f"Error in {event_type.value} handler {handler.__name__}: {e}")
+    
+    async def invoke_auth_handlers(self, agent, task, event) -> None:
+        """
+        Invoke all registered authentication event handlers.
+        
+        Args:
+            agent: The Agent object associated with the task.
+            task: The Task object being executed.
+            event: The TaskUpdateEvent containing authentication event data.
+        """
+        await self.invoke_handlers(EventType.AUTH_EVENT, agent, task, event)
+    
+    def has_handlers(self, event_type: EventType) -> bool:
+        """
+        Check if any handlers are registered for a specific event type.
+        
+        Args:
+            event_type (EventType): The type of event.
+        
+        Returns:
+            bool: True if at least one handler is registered, False otherwise.
+        """
+        return len(self._handlers.get(event_type, [])) > 0
+    
+    def has_auth_handlers(self) -> bool:
+        """
+        Check if any authentication event handlers are registered.
+        
+        Returns:
+            bool: True if at least one auth handler is registered, False otherwise.
+        """
+        return self.has_handlers(EventType.AUTH_EVENT)
+    
+    @classmethod
+    def reset(cls) -> None:
+        """
+        Reset the singleton instance.
+        
+        Useful for testing to ensure a clean state.
+        """
+        if cls._instance is not None:
+            cls._instance.clear()
+            cls._instance = None