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

xpander_sdk/models/frameworks.py

@@ -0,0 +1,64 @@
+from enum import Enum
+from typing import List, Optional
+from pydantic import BaseModel
+
+
+class Framework(str, Enum):
+    """
+    Enum representing supported frameworks within xpander.ai.
+
+    Attributes:
+        Agno (str): Agno framework identifier.
+    """
+
+    Agno = "agno"
+    GoogleADK = "google-adk"
+    LangChain = "langchain"
+    OpenAIAgents = "open-ai-agents"
+    Strands = "strands-agents"
+
+class AgnoToolCallsCompressionSettings(BaseModel):
+    enabled: Optional[bool] = False
+    threshold: Optional[int] = 3
+    instructions: Optional[str] = ""
+
+class AgnoSettings(BaseModel):
+    """
+    Configuration settings specific to the Agno framework.
+
+    Attributes:
+        session_storage (Optional[bool]): If True, enables session-level storage. Default is True.
+        user_memories (Optional[bool]): If True, enables memory of user interactions. Default is True.
+        session_summaries (Optional[bool]): If True, enables generation of session summaries. Default is False.
+        num_history_runs (Optional[int]): Number of historical runs to retain or consider. Default is 3.
+        tool_call_limit (Optional[int]): Max tool calls per run.
+        coordinate_mode (Optional[bool]): If True, The agent will be loaded as a Team. Default is False.
+        pii_detection_enabled (Optional[bool]): If True, enables PII detection guardrail on agent input. Default is False.
+        pii_detection_mask (Optional[bool]): If True, masks detected PII instead of blocking. Default is False.
+        prompt_injection_detection_enabled (Optional[bool]): If True, enables prompt injection detection guardrail. Default is False.
+        openai_moderation_enabled (Optional[bool]): If True, enables OpenAI content moderation guardrail. Default is False.
+        openai_moderation_categories (Optional[List[str]]): List of specific OpenAI moderation categories to enforce. If None, all categories are checked.
+        reasoning_tools_enabled (Optional[bool]): If True, enables Agno's reasoning tools (analyze, think, instructions and few shot). Default is False.
+    """
+
+    session_storage: Optional[bool] = True
+    
+    user_memories: Optional[bool] = False
+    agentic_memory: Optional[bool] = False
+    
+    agent_memories: Optional[bool] = False
+    agentic_culture: Optional[bool] = False
+    
+    session_summaries: Optional[bool] = False
+    num_history_runs: Optional[int] = 3
+    max_tool_calls_from_history: Optional[int] = 0
+    tool_call_limit: Optional[int] = None
+    coordinate_mode: Optional[bool] = False
+    pii_detection_enabled: Optional[bool] = False
+    pii_detection_mask: Optional[bool] = True
+    prompt_injection_detection_enabled: Optional[bool] = False
+    openai_moderation_enabled: Optional[bool] = False
+    openai_moderation_categories: Optional[List[str]] = None
+    reasoning_tools_enabled: Optional[bool] = False
+    
+    tool_calls_compression: Optional[AgnoToolCallsCompressionSettings] = None

xpander_sdk/models/shared.py

@@ -0,0 +1,102 @@
+"""
+Shared models and utilities for the xpander.ai SDK.
+
+This module contains common base classes, enums, and type definitions used
+across the entire SDK for consistent data handling and serialization.
+"""
+
+from abc import ABC
+from enum import Enum
+import json
+from typing import Optional
+from pydantic import BaseModel, computed_field
+
+
+class XPanderSharedModel(BaseModel):
+    """
+    Base model class for all xpander.ai SDK models.
+    
+    This class extends Pydantic's BaseModel with additional functionality
+    for safe serialization of complex data types including Enums.
+    
+    Methods:
+        model_dump_safe: Safely serialize the model with proper Enum handling.
+    """
+    
+    def model_dump_safe(self, **kwargs) -> dict:
+        """
+        Safely serialize the model to a dictionary with proper Enum handling.
+        
+        This method ensures that Enum values are properly serialized as their
+        string representations rather than Enum objects, making the output
+        JSON-compatible and suitable for API requests.
+        
+        Args:
+            **kwargs: Additional keyword arguments passed to model_dump_json().
+            
+        Returns:
+            dict: A dictionary representation of the model with all values
+                 properly serialized for JSON compatibility.
+                 
+        Example:
+            >>> class MyModel(XPanderSharedModel):
+            ...     format: OutputFormat = OutputFormat.Json
+            >>> model = MyModel()
+            >>> model.model_dump_safe()
+            {'format': 'json'}
+        """
+        return json.loads(self.model_dump_json(**kwargs))
+
+
+class OutputFormat(str, Enum):
+    """
+    Enumeration of supported output formats for xpander.ai operations.
+    
+    This enum defines the various output formats that can be used when
+    requesting data from xpander.ai services, allowing for flexible
+    response formatting based on use case requirements.
+    
+    Values:
+        Text: Plain text format for simple string responses.
+        Markdown: Markdown format for rich text with formatting.
+        Json: JSON format for structured data responses.
+        
+    Example:
+        >>> format_type = OutputFormat.Markdown
+        >>> print(format_type.value)
+        'markdown'
+    """
+    
+    Text = "text"
+    Markdown = "markdown"
+    Json = "json"
+
+
+# Type alias for Language Model types
+LLMModelT = type[ABC]
+"""
+Type alias for Language Model types.
+
+This type alias is used throughout the SDK to represent different
+LLM (Large Language Model) implementations that can be used with xpander.ai.
+The models should inherit from ABC (Abstract Base Class) to ensure
+proper interface implementation.
+"""
+
+class Tokens(BaseModel):
+    completion_tokens: Optional[int] = 0
+    prompt_tokens: Optional[int] = 0
+    
+    @computed_field
+    @property
+    def total_tokens(self) -> int:
+        return self.completion_tokens+self.prompt_tokens
+
+
+class ExecutionTokens(BaseModel):
+    inner: Optional[Tokens] = Tokens()
+    worker: Optional[Tokens] = Tokens()
+
+class ThinkMode(str, Enum):
+    Default = "default"
+    Harder = "harder"

xpander_sdk/models/user.py

@@ -0,0 +1,21 @@
+from typing import Optional
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    """
+    Represents the details of a user.
+
+    Attributes:
+        id (Optional[str]): The unique identifier of the user. Defaults to None.
+        first_name (Optional[str]): The first name of the user. Defaults to None.
+        last_name (Optional[str]): The last name of the user. Defaults to None.
+        email (str): The email address of the user. This field is required.
+        additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service.
+    """
+
+    id: Optional[str] = None
+    first_name: Optional[str] = None
+    last_name: Optional[str] = None
+    email: str
+    additional_attributes: Optional[dict] = None

xpander_sdk/modules/agents/agents_module.py

@@ -0,0 +1,164 @@
+"""
+Agents module for managing AI agents in the xpander.ai platform.
+
+This module provides functionality to list, retrieve, and manage AI agents
+within the xpander.ai Backend-as-a-Service platform.
+"""
+
+from typing import List, Optional
+from os import getenv
+from httpx import HTTPStatusError
+
+from xpander_sdk.consts.api_routes import APIRoute
+from xpander_sdk.core.module_base import ModuleBase
+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.modules.agents.models.agent_list import AgentsListItem
+from xpander_sdk.modules.agents.sub_modules.agent import Agent
+from xpander_sdk.utils.event_loop import run_sync
+
+
+class Agents(ModuleBase):
+    """
+    Main module for managing AI agents in xpander.ai.
+    
+    This class provides both synchronous and asynchronous methods for listing
+    and retrieving AI agents from the xpander.ai platform. It handles agent
+    discovery, versioning, and provides access to individual agent instances.
+    
+    The module follows the singleton pattern inherited from ModuleBase,
+    ensuring consistent configuration across all agent operations.
+    
+    Example:
+        >>> agents = Agents()
+        >>> agent_list = agents.list()
+        >>> specific_agent = agents.get("agent-id-123")
+        >>> specific_version = agents.get("agent-id-123", version=2)
+    """
+    
+    def __init__(self, configuration: Optional[Configuration] = None):
+        """
+        Initialize the Agents module.
+        
+        Args:
+            configuration (Optional[Configuration]): SDK configuration. If None,
+                will use default configuration from environment variables.
+        """
+        super().__init__(configuration)
+
+    async def alist(self) -> List[AgentsListItem]:
+        """
+        Asynchronously list all available agents.
+        
+        Retrieves a list of all agents accessible to the current user/organization.
+        Each item in the list contains basic agent information including ID, name,
+        status, and metadata.
+        
+        Returns:
+            List[AgentsListItem]: List of agent summary objects containing
+                basic information about each agent.
+                
+        Raises:
+            ModuleException: If the API request fails or returns an error.
+                The exception will contain the HTTP status code and error message.
+                
+        Example:
+            >>> agents = Agents()
+            >>> agent_list = await agents.alist()
+            >>> for agent in agent_list:
+            ...     print(f"Agent: {agent.name} (ID: {agent.id})")
+        """
+        try:
+            client = APIClient(configuration=self.configuration)
+            agents = await client.make_request(path=APIRoute.ListAgent)
+            return [AgentsListItem(**agent) for agent in agents]
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to list agents - {str(e)}")
+
+    def list(self) -> List[AgentsListItem]:
+        """
+        Synchronously list all available agents.
+        
+        This is the synchronous version of alist(). It internally calls the
+        asynchronous method and waits for completion.
+        
+        Returns:
+            List[AgentsListItem]: List of agent summary objects containing
+                basic information about each agent.
+                
+        Raises:
+            ModuleException: If the API request fails or returns an error.
+            
+        Example:
+            >>> agents = Agents()
+            >>> agent_list = agents.list()
+            >>> print(f"Found {len(agent_list)} agents")
+        """
+        return run_sync(self.alist())
+
+    async def aget(self, agent_id: Optional[str] = None, version: Optional[int] = None) -> Agent:
+        """
+        Asynchronously retrieve a specific agent by ID.
+        
+        Loads and returns a full Agent object with complete configuration,
+        graph definitions, and all associated metadata. Optionally loads
+        a specific version of the agent.
+        
+        Args:
+            agent_id (Optional[str]): Unique identifier of the agent to retrieve, Fallback to XPANDER_AGENT_ID.
+            version (Optional[int]): Specific version number to load. If None,
+                loads the latest version.
+                
+        Returns:
+            Agent: Complete agent object with full configuration and capabilities.
+            
+        Raises:
+            ModuleException: If the agent is not found, access is denied,
+                or the API request fails.
+                
+        Example:
+            >>> agents = Agents()
+            >>> agent = await agents.aget("agent-123")
+            >>> print(f"Loaded agent: {agent.name}")
+            
+            >>> # Load specific version
+            >>> agent_v2 = await agents.aget("agent-123", version=2)
+        """
+        return await Agent.aload(
+            agent_id=agent_id or self.configuration.agent_id or getenv("XPANDER_AGENT_ID"),
+            configuration=self.configuration, version=version
+        )
+
+    def get(self, agent_id: Optional[str] = None, version: Optional[int] = None) -> Agent:
+        """
+        Synchronously retrieve a specific agent by ID.
+        
+        This is the synchronous version of aget(). It internally calls the
+        asynchronous method and waits for completion.
+        
+        Args:
+            agent_id (Optional[str]): Unique identifier of the agent to retrieve, Fallback to XPANDER_AGENT_ID.
+            version (Optional[int]): Specific version number to load. If None,
+                loads the latest version.
+                
+        Returns:
+            Agent: Complete agent object with full configuration and capabilities.
+            
+        Raises:
+            ModuleException: If the agent is not found, access is denied,
+                or the API request fails.
+                
+        Example:
+            >>> agents = Agents()
+            >>> agent = agents.get("agent-123")
+            >>> result = agent.execute("What is the weather today?")
+        """
+        return run_sync(
+            self.aget(
+            agent_id=agent_id,
+            version=version
+            )
+        )