xpander-sdk 2.0.144__py3-none-any.whl → 2.0.192__py3-none-any.whl

xpander_sdk/modules/agents/models/agent.py

@@ -10,6 +10,7 @@ from enum import Enum
 from typing import Dict, List, Literal, Optional, Type
 from pydantic import BaseModel, computed_field
 
+from xpander_sdk.models.orchestrations import OrchestrationIterativeStrategy, OrchestrationRetryStrategy, OrchestrationStopStrategy
 from xpander_sdk.models.shared import XPanderSharedModel
 from xpander_sdk.modules.tools_repository.models.mcp import MCPServerDetails
 
@@ -383,7 +384,10 @@ class AgentGraphItem(BaseModel):
     llm_settings: Optional[List[AgentGraphItemLLMSettings]] = []
     is_first: Optional[bool] = False
 
-
+class LLMReasoningEffort(str, Enum):
+    Low = "low"
+    Medium = "medium"
+    High = "high"
 
 class AIAgentConnectivityDetailsA2AAuthType(str, Enum):
     NoAuth = "none"
@@ -417,12 +421,14 @@ class AgentType(str, Enum):
         Regular: Standard agent for individual task execution.
         A2A: Agent that is used via A2A protocol.
         Curl: Custom Agent that is used via curl.
+        Orchestration: marks the agent as an Orchestration object.
     """
 
     Manager = "manager"
     Regular = "regular"
     A2A = "a2a"
     Curl = "curl"
+    Orchestration = "orchestration"
 
 
 @dataclass
@@ -468,7 +474,7 @@ class AgentOutput(BaseModel):
     is_markdown: Optional[bool] = False
     use_json_mode: Optional[bool] = False
 
-class LLMCredentials(XPanderSharedModel):
-    name: str
-    description: Optional[str] = None
-    value: str
+class TaskLevelStrategies(XPanderSharedModel):
+    retry_strategy: Optional[OrchestrationRetryStrategy] = None
+    iterative_strategy: Optional[OrchestrationIterativeStrategy] = None
+    stop_strategy: Optional[OrchestrationStopStrategy] = None

xpander_sdk/modules/agents/sub_modules/agent.py

@@ -19,6 +19,8 @@ from xpander_sdk.core.xpander_api_client import APIClient
 from xpander_sdk.exceptions.module_exception import ModuleException
 from xpander_sdk.models.configuration import Configuration
 from xpander_sdk.models.frameworks import AgnoSettings, Framework
+from xpander_sdk.models.notifications import NotificationSettings
+from xpander_sdk.models.orchestrations import OrchestrationNode
 from xpander_sdk.modules.agents.utils.generic import get_db_schema_name
 from xpander_sdk.modules.knowledge_bases.models.knowledge_bases import (
     KnowledgeBaseSearchResult,
@@ -39,8 +41,10 @@ from xpander_sdk.modules.agents.models.agent import (
     AgentStatus,
     AgentType,
     DatabaseConnectionString,
-    LLMCredentials,
+    LLMReasoningEffort,
+    TaskLevelStrategies,
 )
+from xpander_sdk.models.generic import LLMCredentials
 from xpander_sdk.modules.agents.models.knowledge_bases import AgentKnowledgeBase
 from xpander_sdk.modules.knowledge_bases.knowledge_bases_module import KnowledgeBases
 from xpander_sdk.modules.knowledge_bases.sub_modules.knowledge_base import KnowledgeBase
@@ -151,6 +155,9 @@ class Agent(XPanderSharedModel):
             using_nemo: Optional[bool]
             model_provider: str
             model_name: str
+            llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
+            deep_planning: Optional[bool] = False
+            enforce_deep_planning: Optional[bool] = False
             llm_api_base: Optional[str]
             webhook_url: Optional[str]
             created_at: Optional[datetime]
@@ -161,6 +168,9 @@ class Agent(XPanderSharedModel):
             llm_credentials: Optional[LLMCredentials]
             expected_output: Optional[str]
             agno_settings: Optional[AgnoSettings]
+            orchestration_nodes: Optional[List[OrchestrationNode]] = []
+            notification_settings: Optional[NotificationSettings] = {}
+            task_level_strategies: Optional[TaskLevelStrategies] = None
 
         Example:
             >>> agent = Agent(id="agent123", name="Example Agent")
@@ -192,6 +202,9 @@ class Agent(XPanderSharedModel):
     using_nemo: Optional[bool] = False
     model_provider: str
     model_name: str
+    llm_reasoning_effort: Optional[LLMReasoningEffort] = LLMReasoningEffort.Medium
+    deep_planning: Optional[bool] = False
+    enforce_deep_planning: Optional[bool] = False
     llm_api_base: Optional[str] = None
     webhook_url: Optional[str] = None
     created_at: Optional[datetime] = None
@@ -202,6 +215,9 @@ class Agent(XPanderSharedModel):
     llm_credentials: Optional[LLMCredentials] = None
     expected_output: Optional[str] = ""
     agno_settings: Optional[AgnoSettings] = AgnoSettings()
+    orchestration_nodes: Optional[List[OrchestrationNode]] = []
+    notification_settings: Optional[NotificationSettings] = {}
+    task_level_strategies: Optional[TaskLevelStrategies] = None
 
     _connection_string: Optional[DatabaseConnectionString] = None
 
@@ -621,12 +637,12 @@ class Agent(XPanderSharedModel):
         schema = get_db_schema_name(agent_id=self.id)
         
         client_type = AsyncPostgresDb if async_db else PostgresDb
-
+        
         return client_type(
             db_schema=schema,
             db_url=connection_string.connection_uri.uri.replace("postgresql", "postgresql+psycopg"+("_async" if async_db else "")),
         )
-
+    
     def get_db(self) -> Any:
         """
         Synchronously retrieve the db for this agent.
@@ -744,9 +760,9 @@ class Agent(XPanderSharedModel):
         Example:
             >>> sessions = await agent.aget_user_sessions(user_id="user_123")
         """
-        db = await self.aget_db()
+        db = await self.aget_db(async_db=True)
         from agno.db import SessionType
-        sessions = await asyncio.to_thread(db.get_sessions, user_id=user_id, limit=50, session_type = SessionType.TEAM if self.is_a_team else SessionType.AGENT)
+        sessions = await db.get_sessions(user_id=user_id, limit=50, session_type = SessionType.TEAM if self.is_a_team else SessionType.AGENT)
         return sessions
     
     def get_user_sessions(self, user_id: str):
@@ -790,10 +806,9 @@ class Agent(XPanderSharedModel):
         Example:
             >>> session = await agent.aget_session(session_id="sess_456")
         """
-        db = await self.aget_db()
+        db = await self.aget_db(async_db=True)
         from agno.db import SessionType
-        session = await asyncio.to_thread(db.get_session, session_id=session_id, session_type = SessionType.TEAM if self.is_a_team else SessionType.AGENT)
-        return await session
+        return await db.get_session(session_id=session_id, session_type = SessionType.TEAM if self.is_a_team else SessionType.AGENT)
 
     def get_session(self, session_id: str):
         """
@@ -834,8 +849,8 @@ class Agent(XPanderSharedModel):
         Example:
             >>> await agent.adelete_session(session_id="sess_456")
         """
-        db = await self.aget_db(async_db=False)
-        await asyncio.to_thread(db.delete_session, session_id=session_id)
+        db = await self.aget_db(async_db=True)
+        await db.delete_session(session_id=session_id)
     
     def delete_session(self, session_id: str):
         """

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/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/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/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/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