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

xpander_sdk/consts/api_routes.py

@@ -0,0 +1,63 @@
+"""
+API routes configuration for the xpander.ai SDK.
+
+This module defines all API endpoint paths used by the xpander.ai SDK for
+autonomous agent management, task operations, and knowledge base interactions.
+"""
+
+from enum import Enum
+
+
+class APIRoute(str, Enum):
+    """
+    Enumeration of API endpoints for xpander.ai services.
+    
+    This class defines the paths for interacting with various APIs, including
+    agents, tasks, and knowledge bases, standardizing route management across
+the SDK.
+    
+    Attributes include paths for listing, retrieving, creating, updating,
+and deleting resources.
+    
+    Example:
+        >>> route = APIRoute.ListAgent
+        >>> print(route)  # Outputs: /agents/list
+    """
+    
+    # Agents Endpoints
+    ListAgent = "/agents/list"
+    GetAgent = "/agents/{agent_id}"
+    SyncLocalTools = "/agents/{agent_id}/sync_local_tools"
+    GetAgentConnectionString = "/agents/{agent_id}/db"
+    InvokeTool = "/agents/{agent_id}/operations/{tool_id}"
+    
+    # Tasks Endpoints
+    ListTasks = "/agent-execution/executions/history/{agent_id}"
+    ListUserTasks = "/agent-execution/executions/history/user/{user_id}"
+    GetTask = "/agent-execution/{task_id}/status"
+    GetTaskActivityLog = "/activity/{agent_id}/{task_id}"
+    TaskCrud = "/agent-execution/{agent_or_task_id}"
+    UpdateTask = "/agent-execution/{task_id}/update"
+    ReportExternalTask = "/agent-execution/{agent_id}/report_task"
+    ReportExecutionMetrics = "/agents-metrics/{agent_id}/execution"
+    PushExecutionEventToQueue = "/agent-execution/{task_id}/events/push"
+    
+    # Knowledge Bases Endpoints
+    ListKnowledgeBases = "/knowledge_bases"
+    CreateKnowledgeBase = "/knowledge_bases/create"
+    DeleteKnowledgeBase = "/knowledge_bases/{knowledge_base_id}/erase"
+    ListKnowledgeBaseDocuments = "/knowledge_bases/{knowledge_base_id}/list"
+    KnowledgeBaseDocumentsCrud = "/knowledge_bases/{knowledge_base_id}"
+    GetKnowledgeBaseDetails = "/knowledge_bases/{knowledge_base_id}/details"
+    
+    # MCP Auth
+    GetUserMCPAuthToken = "/mcp_auth/{agent_id}/{user_id}/get_token"
+    
+    # Tools
+    GetOrInvokeToolById = "/tools/{tool_id}"
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        return str(self.value)

xpander_sdk/core/module_base.py

@@ -0,0 +1,164 @@
+"""
+Base class for all xpander.ai SDK modules.
+
+This module provides the abstract base class that all SDK modules inherit from,
+establishing common patterns for resource management and API operations.
+"""
+
+from abc import ABC
+from typing import Optional, Any, Dict, Type
+from xpander_sdk.models.configuration import Configuration
+
+
+class ModuleBase(ABC):
+    """
+    Abstract base class for all xpander.ai SDK modules.
+    
+    This class implements a conditional singleton pattern:
+    - If no configuration is passed, it returns a shared singleton per subclass.
+    - If a configuration is passed, a new instance is created and not shared.
+    
+    Attributes:
+        configuration (Configuration): SDK configuration including API credentials
+            and endpoint information.
+            
+    Abstract Methods:
+        list: List all resources of this module type.
+        get: Retrieve a single resource by ID.
+        
+    Optional Methods (can be overridden by subclasses):
+        create: Create a new resource.
+        update: Update an existing resource.
+        delete: Delete a resource.
+    """
+
+    _shared_instances: Dict[Type['ModuleBase'], 'ModuleBase'] = {}
+
+    def __new__(cls, configuration: Optional[Configuration] = None):
+        """
+        Create or return an existing module singleton instance.
+        
+        Args:
+            configuration (Optional[Configuration]): If provided, a new independent
+                instance is created. Otherwise, returns a singleton per class.
+                
+        Returns:
+            ModuleBase: The module instance.
+        """
+        if configuration is not None:
+            instance = super().__new__(cls)
+            instance._is_custom_instance = True
+            return instance
+
+        if cls not in cls._shared_instances:
+            instance = super().__new__(cls)
+            instance._is_custom_instance = False
+            cls._shared_instances[cls] = instance
+
+        return cls._shared_instances[cls]
+
+    def __init__(self, configuration: Optional[Configuration] = None):
+        """
+        Initialize the module with configuration.
+        
+        This method is called only once per instance to prevent reinitialization.
+        
+        Args:
+            configuration (Optional[Configuration]): SDK configuration. If None,
+                will create a default Configuration instance from environment variables.
+        """
+        if hasattr(self, '_initialized') and self._initialized:
+            return
+
+        self.configuration = configuration or Configuration()
+        self._initialized = True
+
+    async def list(self, **kwargs) -> Any:
+        """
+        List all resources of this module type.
+
+        This is an abstract method that must be implemented by concrete module classes.
+        
+        Args:
+            **kwargs: Additional parameters for filtering, pagination, etc.
+                
+        Returns:
+            Any: List of resources or paginated response.
+            
+        Raises:
+            NotImplementedError: Always, unless overridden.
+        """
+        raise NotImplementedError
+
+    async def get(self, resource_id: str, **kwargs) -> Any:
+        """
+        Retrieve a single resource by its unique identifier.
+        
+        This is an abstract method that must be implemented by concrete module classes.
+        
+        Args:
+            resource_id (str): Unique identifier of the resource to retrieve.
+            **kwargs: Additional retrieval options.
+            
+        Returns:
+            Any: The resource data.
+            
+        Raises:
+            NotImplementedError: Always, unless overridden.
+        """
+        raise NotImplementedError
+
+    async def create(self, data: dict, **kwargs) -> Any:
+        """
+        Create a new resource (optional operation).
+        
+        Can be overridden by modules that support creation.
+        
+        Args:
+            data (dict): Resource data.
+            **kwargs: Additional creation options.
+            
+        Returns:
+            Any: Created resource data.
+            
+        Raises:
+            NotImplementedError: If creation is not supported.
+        """
+        raise NotImplementedError("This module does not support 'create'")
+
+    async def update(self, resource_id: str, data: dict, **kwargs) -> Any:
+        """
+        Update an existing resource by ID (optional operation).
+        
+        Can be overridden by modules that support updates.
+        
+        Args:
+            resource_id (str): Unique ID of resource to update.
+            data (dict): Updated data.
+            **kwargs: Additional update options.
+            
+        Returns:
+            Any: Updated resource data.
+            
+        Raises:
+            NotImplementedError: If update is not supported.
+        """
+        raise NotImplementedError("This module does not support 'update'")
+
+    async def delete(self, resource_id: str, **kwargs) -> Any:
+        """
+        Delete a resource by ID (optional operation).
+        
+        Can be overridden by modules that support deletion.
+        
+        Args:
+            resource_id (str): Unique ID of resource to delete.
+            **kwargs: Additional deletion options.
+            
+        Returns:
+            Any: Deletion result.
+            
+        Raises:
+            NotImplementedError: If delete is not supported.
+        """
+        raise NotImplementedError("This module does not support 'delete'")

xpander_sdk/core/state.py

@@ -0,0 +1,10 @@
+from asyncio import Task
+from typing import Any, Optional
+
+
+from xpander_sdk.models.shared import XPanderSharedModel
+
+
+class State(XPanderSharedModel):
+    task: Optional[Any] = None
+    agent: Optional[Any] = None

xpander_sdk/core/xpander_api_client.py

@@ -0,0 +1,119 @@
+"""
+API client for communicating with xpander.ai services.
+
+This module provides the core HTTP client functionality for making authenticated
+requests to the xpander.ai Backend-as-a-Service platform.
+"""
+
+from abc import ABC
+from typing import Optional, Any, Literal, Dict
+import httpx
+from pydantic import BaseModel
+
+from xpander_sdk.models.configuration import Configuration
+
+# Type alias for supported HTTP methods
+HTTPMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
+
+
+class APIClient(ABC):
+    """
+    Conditional singleton HTTP client for xpander.ai API communication.
+    
+    - If no configuration is passed, uses a shared singleton instance.
+    - If a configuration is passed, creates a unique instance.
+    
+    This client handles:
+    - API key authentication via x-api-key header
+    - URL construction
+    - JSON serialization/deserialization
+    - Extended timeouts
+    - HTTP error handling
+    """
+
+    _shared_instances: Dict[type, 'APIClient'] = {}
+
+    def __new__(cls, configuration: Optional[Configuration] = None):
+        """
+        Returns a shared singleton if no configuration is passed.
+        If configuration is provided, returns a unique instance.
+        """
+        if configuration is not None:
+            instance = super().__new__(cls)
+            instance._is_custom_instance = True
+            return instance
+
+        if cls not in cls._shared_instances:
+            instance = super().__new__(cls)
+            instance._is_custom_instance = False
+            cls._shared_instances[cls] = instance
+
+        return cls._shared_instances[cls]
+
+    def __init__(self, configuration: Optional[Configuration] = None):
+        """
+        Initialize the APIClient with configuration, once per instance.
+        """
+        if hasattr(self, '_initialized') and self._initialized:
+            return
+
+        self.configuration = configuration or Configuration()
+        self._initialized = True
+
+    async def make_request(
+        self,
+        path: str,
+        method: HTTPMethod = "GET",
+        payload: Optional[Any] = None,
+        query: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, Any]] = None,
+        configuration: Optional[Configuration] = None,
+        model: Optional[BaseModel] = None,
+    ) -> Any:
+        """
+        Make an authenticated HTTP request to the xpander.ai API.
+
+        Args:
+            path (str): Endpoint path (e.g., "/agents").
+            method (HTTPMethod): HTTP verb.
+            payload (Optional[Any]): JSON body for POST/PUT/PATCH.
+            query (Optional[Dict[str, Any]]): Query string parameters.
+            headers (Optional[Dict[str, Any]]): Extra headers.
+            configuration (Optional[Configuration]): Overrides self.configuration.
+            model (Optional[BaseModel]): pydantic model to use when constructing the result.
+        
+        Returns:
+            Any: Parsed response body (JSON or text).
+        
+        Raises:
+            httpx.HTTPStatusError: For 4xx/5xx responses.
+            httpx.RequestError: For connection/network errors.
+        """
+        config = configuration or self.configuration
+
+        # Construct full URL
+        url = f"{config.get_full_url().rstrip('/')}/{path.lstrip('/')}"
+
+        # Prepare headers
+        headers = headers.copy() if headers else {}
+        headers["x-api-key"] = config.api_key
+
+        async with httpx.AsyncClient() as client:
+            response = await client.request(
+                method=method,
+                url=url,
+                json=payload if method in {"POST", "PUT", "PATCH"} else None,
+                params=query,
+                headers=headers,
+                timeout=1200,  # 20 minutes
+            )
+
+            response.raise_for_status()
+
+            content_type = response.headers.get("Content-Type", "")
+            if "application/json" in content_type:
+                try:
+                    return response.json() if not model else model(**response.json())
+                except Exception:
+                    return response.text
+            return response.text

xpander_sdk/exceptions/module_exception.py

@@ -0,0 +1,45 @@
+"""
+Custom exception classes for the xpander.ai SDK.
+
+This module defines SDK-specific exception types for better error handling
+and debugging throughout the xpander.ai Backend-as-a-Service platform.
+"""
+
+
+class ModuleException(Exception):
+    """
+    Custom exception for xpander.ai SDK module operations.
+    
+    This exception is raised when SDK modules encounter errors during API
+    operations, providing structured error information including HTTP status
+    codes and detailed error descriptions.
+    
+    Attributes:
+        status_code (int): HTTP status code associated with the error.
+        description (str): Detailed description of the error.
+        
+    Example:
+        >>> try:
+        ...     agents = Agents()
+        ...     agent = agents.get("invalid-id")
+        ... except ModuleException as e:
+        ...     print(f"Error {e.status_code}: {e.description}")
+        ...     # Error 404: Agent not found
+    """
+    
+    def __init__(self, status_code: int, description: str):
+        """
+        Initialize a ModuleException with status code and description.
+        
+        Args:
+            status_code (int): HTTP status code representing the error type
+                (e.g., 404 for not found, 401 for unauthorized, 500 for server error).
+            description (str): Human-readable description of the error condition.
+                
+        Example:
+            >>> raise ModuleException(404, "Agent with ID 'xyz' not found")
+            >>> raise ModuleException(401, "Invalid API key provided")
+        """
+        self.status_code = status_code
+        self.description = description
+        super().__init__(f"[{status_code}] {description}")

xpander_sdk/models/activity.py

@@ -0,0 +1,65 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any, List, Literal, Optional, Union
+
+from xpander_sdk.models.events import ToolCallRequestReasoning
+from xpander_sdk.models.shared import XPanderSharedModel
+from xpander_sdk.models.user import User
+from xpander_sdk.modules.tools_repository.models.mcp import MCPOAuthGetTokenResponse
+
+class AgentActivityThreadMessageContent(XPanderSharedModel):
+    text: Optional[str] = None
+    files: Optional[List[str]] = []
+
+class AgentActivityThreadMessage(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    role: Literal["user","agent"]
+    content: AgentActivityThreadMessageContent
+
+class AgentActivityThreadToolCall(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    tool_name: str
+    payload: Any
+    is_error: Optional[bool] = False
+    reasoning: Optional[ToolCallRequestReasoning] = None
+    result: Optional[Any] = None
+
+class AgentActivityThreadReasoningType(str, Enum):
+    Think = "think"
+    Analyze = "analyze"
+
+class AgentActivityThreadReasoning(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    type: AgentActivityThreadReasoningType
+    title: str
+    confidence: float
+    thought: Optional[str] = None
+    action: Optional[str] = None
+    result: Optional[str] = None
+    analysis: Optional[str] = None
+
+class AgentActivityThreadSubAgentTrigger(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    agent_id: str
+    query: Optional[str] = None
+    files: Optional[List[str]] = []
+    reasoning: ToolCallRequestReasoning
+
+class AgentActivityThreadAuth(MCPOAuthGetTokenResponse):
+    id: str
+    created_at: datetime
+
+AgentActivityThreadMessageType = Union[AgentActivityThreadMessage, AgentActivityThreadToolCall, AgentActivityThreadReasoning, AgentActivityThreadSubAgentTrigger, AgentActivityThreadAuth]
+class AgentActivityThread(XPanderSharedModel):
+    id: str
+    created_at: datetime
+    messages: List[AgentActivityThreadMessageType]
+    user: Optional[User] = None
+
+class AgentActivityThreadListItem(XPanderSharedModel):
+    id: str
+    created_at: datetime

xpander_sdk/models/configuration.py

@@ -0,0 +1,92 @@
+"""
+Configuration model for xpander.ai SDK.
+
+This module contains the Configuration class that manages SDK settings including
+API credentials, base URLs, and organization information.
+"""
+
+from typing import Optional
+from os import getenv
+from pydantic import BaseModel, Field
+
+from xpander_sdk.core.state import State
+from xpander_sdk.utils.env import get_base_url
+
+
+class Configuration(BaseModel):
+    """
+    Configuration settings for the xpander.ai SDK.
+    
+    This class manages all configuration parameters required to connect to the xpander.ai
+    Backend-as-a-Service platform, including authentication credentials and service endpoints.
+    
+    Attributes:
+        api_key (Optional[str]): Your xpander.ai API key. Defaults to XPANDER_API_KEY environment variable.
+        base_url (Optional[str]): The base URL for xpander.ai API endpoints. Auto-detected from environment.
+        organization_id (Optional[str]): Your organization ID. Defaults to XPANDER_ORGANIZATION_ID environment variable.
+    
+    Environment Variables:
+        XPANDER_API_KEY: Your API key for authentication
+        XPANDER_ORGANIZATION_ID: Your organization identifier
+        
+    Example:
+        >>> config = Configuration(
+        ...     api_key="your-api-key",
+        ...     organization_id="your-org-id"
+        ... )
+        >>> full_url = config.get_full_url()
+    """
+    
+    api_key: Optional[str] = Field(
+        default_factory=lambda: getenv(key="XPANDER_API_KEY"),
+        description="xpander.ai API key for authentication",
+    )
+    
+    base_url: Optional[str] = Field(
+        default_factory=get_base_url, 
+        description="Base URL for xpander.ai API endpoints"
+    )
+    
+    agent_id: Optional[str] = Field(
+        default= None, 
+        description="Agent ID To work on"
+    )
+    
+    organization_id: Optional[str] = Field(
+        default_factory=lambda: getenv(key="XPANDER_ORGANIZATION_ID"),
+        description="Organization identifier for xpander.ai account",
+    )
+    
+    state: Optional[State] = Field(
+        default_factory=State,
+        description="Configuration level in-memory state",
+        exclude=True,  # This ensures it's excluded by default
+    )
+
+    def get_full_url(self) -> str:
+        """
+        Construct the complete API URL including organization ID when required.
+        
+        Some xpander.ai services require the organization ID to be included in the URL path.
+        This method automatically detects when this is needed and constructs the appropriate URL.
+        
+        Returns:
+            str: The complete URL for API requests, with organization ID included if required.
+            
+        Example:
+            >>> config = Configuration(base_url="https://inbound.xpander.ai", organization_id="org123")
+            >>> config.get_full_url()
+            'https://inbound.xpander.ai'
+            
+            >>> config = Configuration(base_url="https://agent-controller.xpander.ai", organization_id="org123")
+            >>> config.get_full_url()
+            'https://agent-controller.xpander.ai/org123'
+        """
+        should_add_organization_id_to_the_url = (
+            "agent-controller" in self.base_url or "9016" in self.base_url
+        )
+
+        if should_add_organization_id_to_the_url:
+            return f"{self.base_url}/{self.organization_id}"
+
+        return self.base_url

xpander_sdk/models/events.py

@@ -0,0 +1,70 @@
+from enum import Enum
+from typing import Any, List, Optional
+
+from pydantic import Field
+from xpander_sdk.models.shared import XPanderSharedModel
+from datetime import datetime
+
+class TaskStatus(str, Enum):
+    READY = "ready"
+    RUNNING = "running"
+    FAILED = "failed"
+    DONE = "done"
+
+
+class Task(XPanderSharedModel):
+    id: str = Field(..., description="task id")
+    title: str = Field(..., description="Short task title, max 120 chars")
+    description: Optional[str] = Field(None, description="Optional short step description, max 120 chars")
+    status: TaskStatus = Field(..., description="Task status")
+    created_at: datetime = Field(..., description="Creation timestamp (ISO 8601)")
+    started_at: Optional[datetime] = Field(None, description="Start timestamp (ISO 8601)")
+    finished_at: Optional[datetime] = Field(None, description="Finish timestamp (ISO 8601)")
+    error: Optional[str] = Field(None, description="Error message if failed")
+    parent_id: Optional[str] = Field(None, description="Parent task id if related")
+
+class ToolCallRequestReasoning(XPanderSharedModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    
+class ToolCallRequest(XPanderSharedModel):
+    request_id: str
+    operation_id: str
+    tool_call_id: Optional[str] = None
+    graph_node_id: Optional[str] = None
+    tool_name: Optional[str] = None
+    payload: Optional[Any] = None
+    reasoning: Optional[ToolCallRequestReasoning] = None
+
+
+class ToolCallResult(ToolCallRequest):
+    operation_id: str
+    tool_call_id: Optional[str] = None
+    tool_name: Optional[str] = None
+    payload: Optional[Any] = None
+    result: Optional[Any] = None
+    is_error: Optional[bool] = False
+
+
+class TaskUpdateEventType(str, Enum):
+    # tasks
+    TaskCreated = "task_created"
+    TaskUpdated = "task_updated"
+    TaskFinished = "task_finished"
+    
+    # streaming
+    Chunk = "chunk"
+    
+    # MCP Auth
+    AuthEvent = "auth_event"
+
+    # tool calls
+    ToolCallRequest = "tool_call_request"
+    ToolCallResult = "tool_call_result"
+
+    # multi agents
+    SubAgentTrigger = "sub_agent_trigger"
+    
+    # reasoning
+    Think = "think"
+    Analyze = "analyze"