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

xpander_sdk/modules/events/models/events.py

@@ -0,0 +1,57 @@
+import json
+from uuid import uuid4
+from enum import Enum
+from typing import Dict, Optional
+from pydantic import BaseModel, Field, ConfigDict
+from datetime import datetime
+
+from xpander_sdk.modules.tasks.sub_modules.task import Task
+from .deployments import DeployedAsset
+
+
+class EventType(str, Enum):
+    WorkerRegistration = "worker-registration"
+    AgentExecution = "agent-execution"
+    WorkerHeartbeat = "worker-heartbeat"
+    WorkerFinished = "worker-finished"
+    EnvironmentConflict = "worker-environment-conflict"
+
+
+class EventMessageBase(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    event: EventType
+    data: Optional[Dict] = None
+
+    def model_dump_safe(self, **kwargs) -> dict:
+        return json.loads(self.model_dump_json(**kwargs))
+
+    model_config = ConfigDict(
+        use_enum_values=True,
+        ser_json_timedelta='iso8601',
+        ser_json_bytes='utf8'
+    )
+
+
+class WorkerRegistrationEvent(EventMessageBase):
+    event: EventType = EventType.WorkerRegistration
+    data: DeployedAsset
+
+
+class WorkerFinishedEvent(EventMessageBase):
+    event: EventType = EventType.WorkerFinished
+    data: Optional[dict] = {}
+
+
+class WorkerHeartbeat(EventMessageBase):
+    event: EventType = EventType.WorkerHeartbeat
+    data: datetime = Field(default_factory=datetime.now)
+
+
+class WorkerExecutionRequest(EventMessageBase):
+    event: EventType = EventType.AgentExecution
+    data: Task
+
+
+class WorkerEnvironmentConflict(EventMessageBase):
+    event: EventType = EventType.EnvironmentConflict
+    error: str

xpander_sdk/modules/events/utils/generic.py

@@ -0,0 +1,56 @@
+from xpander_sdk.models.configuration import Configuration
+
+EVENT_STREAMING_ENDPOINT = "{base}/{organization_id}/events"
+
+
+def backoff_delay(attempt: int) -> int:
+    """1 s after first failure, 2 s after second, 3 s for attempts ≥ 3."""
+    return 1 if attempt == 1 else 2 if attempt == 2 else 3
+
+
+def is_not_inbound(configuration: Configuration) -> bool:
+    """
+    Determine if the current execution context is not the inbound environment.
+
+    Returns:
+        bool: True if the base_url is not identified as an inbound service.
+    """
+    return (
+        "inbound.xpander" not in configuration.base_url
+        and "inbound.stg.xpander" not in configuration.base_url
+    )
+
+
+def get_events_base(configuration: Configuration) -> str:
+    """
+    Construct the base URL used for event streaming endpoints.
+
+    Returns:
+        str: The base URL for event streaming based on configuration and environment.
+    """
+    if is_not_inbound(configuration=configuration):
+        return EVENT_STREAMING_ENDPOINT.format(
+            base=(
+                "http://localhost:9016"
+                if "8085" in configuration.base_url
+                else configuration.base_url
+            ),
+            organization_id=configuration.organization_id,
+        )
+
+    is_stg = "stg.xpander" in configuration.base_url
+    base = f"https://agent-controller{'.stg' if is_stg else ''}.xpander.ai"
+
+    return EVENT_STREAMING_ENDPOINT.format(
+        base=base, organization_id=configuration.organization_id
+    )
+
+
+def get_events_headers(configuration: Configuration) -> dict[str, str]:
+    """
+    Construct the headers required for requests, including authentication.
+
+    Returns:
+        dict[str, str]: HTTP headers including the API key for authorization.
+    """
+    return {"x-api-key": configuration.api_key}

xpander_sdk/modules/events/utils/git_init.py

@@ -0,0 +1,32 @@
+from os import getenv
+import os
+import subprocess
+from loguru import logger
+
+def configure_git_credentials():
+    try:
+        # Read from environment variables
+        git_user = getenv("GIT_USERNAME", None)
+        git_token = getenv("GIT_TOKEN", None)
+        git_name = getenv("GIT_NAME", "xpander.ai")
+        git_email = getenv("GIT_EMAIL", "agent@xpander.ai")
+
+        if not git_user or not git_token:
+            return
+
+        logger.info(f"Setting up GIT for user {git_user}")
+        # Set Git global config
+        subprocess.run(["git", "config", "--global", "user.name", git_name], check=True)
+        subprocess.run(["git", "config", "--global", "user.email", git_email], check=True)
+        subprocess.run(["git", "config", "--global", "credential.helper", "store"], check=True)
+
+        # Write credentials to ~/.git-credentials
+        cred_line = f"https://{git_user}:{git_token}@github.com\n"
+        git_credentials_path = os.path.expanduser("~/.git-credentials")
+        with open(git_credentials_path, "w") as cred_file:
+            cred_file.write(cred_line)
+
+        logger.info("✅ Git configured with PAT")
+    except Exception as e:
+        logger.warning(f"Failed to configure git {str(e)}")
+

xpander_sdk/modules/knowledge_bases/knowledge_bases_module.py

@@ -0,0 +1,217 @@
+"""
+Knowledge Bases module for managing knowledge repositories in the xpander.ai platform.
+
+This module provides functionality to create, list, and retrieve knowledge bases
+within the xpander.ai Backend-as-a-Service platform.
+"""
+
+from typing import List, Optional
+
+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.knowledge_bases.sub_modules.knowledge_base import KnowledgeBase
+from xpander_sdk.utils.event_loop import run_sync
+
+
+class KnowledgeBases(ModuleBase):
+    """
+    Main module for managing knowledge bases in xpander.ai.
+    
+    This class provides methods for listing, creating, and retrieving knowledge
+    bases associated with AI agents in the xpander.ai platform. Both asynchronous
+    and synchronous versions are offered to accommodate different integration needs.
+    
+    The module follows the singleton pattern inherited from ModuleBase, ensuring
+    consistent configuration across all operations.
+    
+    Example:
+        >>> knowledge_bases = KnowledgeBases()
+        >>> kb_list = knowledge_bases.list()
+        >>> specific_kb = knowledge_bases.get(knowledge_base_id="kb123")
+    """
+    
+    def __init__(self, configuration: Optional[Configuration] = None):
+        """
+        Initialize the KnowledgeBases module.
+        
+        Args:
+            configuration (Optional[Configuration]): SDK configuration. If None,
+                will use default configuration from environment variables.
+        """
+        super().__init__(configuration)
+
+    async def alist(self) -> List[KnowledgeBase]:
+        """
+        Asynchronously list all available knowledge bases.
+        
+        Retrieves a list of all knowledge bases accessible to the current
+        user/organization, providing essential information for exploration and management.
+        
+        Returns:
+            List[KnowledgeBase]: List of knowledge base summary objects.
+            
+        Raises:
+            ModuleException: If the API request fails or returns an error.
+                
+        Example:
+            >>> knowledge_bases = KnowledgeBases()
+            >>> kb_list = await knowledge_bases.alist()
+            >>> for kb in kb_list:
+            ...     print(f"Knowledge Base: {kb.name} (ID: {kb.id})")
+        """
+        try:
+            client = APIClient(configuration=self.configuration)
+            kbs = await client.make_request(path=APIRoute.ListKnowledgeBases)
+            return [KnowledgeBase(**kb, configuration=self.configuration) for kb in kbs]
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to list knowledge bases - {str(e)}")
+
+    def list(self) -> List[KnowledgeBase]:
+        """
+        Synchronously list all available knowledge bases.
+        
+        This is the synchronous version of alist(). It internally calls the
+        asynchronous method and waits for completion.
+        
+        Returns:
+            List[KnowledgeBase]: List of knowledge base summary objects.
+            
+        Raises:
+            ModuleException: If the API request fails or returns an error.
+            
+        Example:
+            >>> knowledge_bases = KnowledgeBases()
+            >>> kb_list = knowledge_bases.list()
+            >>> print(f"Found {len(kb_list)} knowledge bases")
+        """
+        return run_sync(self.alist())
+
+    async def aget(self, knowledge_base_id: str) -> KnowledgeBase:
+        """
+        Asynchronously retrieve a specific knowledge base by ID.
+        
+        Loads and returns a full KnowledgeBase object with detailed configuration
+        and capabilities using the provided knowledge base ID.
+        
+        Args:
+            knowledge_base_id (str): Unique identifier of the knowledge base to retrieve.
+                
+        Returns:
+            KnowledgeBase: Complete knowledge base object.
+            
+        Raises:
+            ModuleException: If the knowledge base is not found or access is denied.
+                
+        Example:
+            >>> knowledge_bases = KnowledgeBases()
+            >>> kb = await knowledge_bases.aget(knowledge_base_id="kb123")
+            >>> print(f"Loaded knowledge base: {kb.name}")
+        """
+        try:
+            client = APIClient(configuration=self.configuration)
+            kb = await client.make_request(
+                path=APIRoute.GetKnowledgeBaseDetails.format(knowledge_base_id=knowledge_base_id)
+            )
+            return KnowledgeBase(**kb, configuration=self.configuration)
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to get knowledge base - {str(e)}")
+
+    def get(self, knowledge_base_id: str) -> KnowledgeBase:
+        """
+        Synchronously retrieve a specific knowledge base by ID.
+        
+        This is the synchronous version of aget(). It internally calls the
+        asynchronous method and waits for completion.
+        
+        Args:
+            knowledge_base_id (str): Unique identifier of the knowledge base to retrieve.
+                
+        Returns:
+            KnowledgeBase: Complete knowledge base object.
+            
+        Raises:
+            ModuleException: If the knowledge base is not found or access is denied.
+                
+        Example:
+            >>> knowledge_bases = KnowledgeBases()
+            >>> kb = knowledge_bases.get(knowledge_base_id="kb123")
+            >>> details = kb.details()
+        """
+        return run_sync(self.aget(knowledge_base_id))
+
+    async def acreate(self, name: str, description: Optional[str] = "") -> KnowledgeBase:
+        """
+        Asynchronously create a new knowledge base.
+        
+        Creates a new knowledge base in the xpander.ai platform with the specified
+        name and description.
+        
+        Args:
+            name (str): The name of the new knowledge base.
+            description (Optional[str]): A brief description of the knowledge base.
+                
+        Returns:
+            KnowledgeBase: Newly created knowledge base object.
+            
+        Raises:
+            ModuleException: If knowledge base creation fails due to API problems or configuration errors.
+                
+        Example:
+            >>> knowledge_bases = KnowledgeBases()
+            >>> new_kb = await knowledge_bases.acreate(
+            ...     name="New Knowledge Base",
+            ...     description="A demo knowledge base for testing"
+            ... )
+            >>> print(f"Created knowledge base: {new_kb.id}")
+        """
+        try:
+            client = APIClient(configuration=self.configuration)
+            created_kb = await client.make_request(
+                path=APIRoute.CreateKnowledgeBase,
+                method="POST",
+                payload={
+                    "name": name,
+                    "description": description,
+                },
+            )
+            return KnowledgeBase(**created_kb, configuration=self.configuration)
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to create knowledge base - {str(e)}")
+
+    def create(self, name: str, description: Optional[str] = "") -> KnowledgeBase:
+        """
+        Synchronously create a new knowledge base.
+        
+        This is the synchronous version of acreate(). It internally calls the
+        asynchronous method and waits for completion.
+        
+        Args:
+            name (str): The name of the new knowledge base.
+            description (Optional[str]): A brief description of the knowledge base.
+                
+        Returns:
+            KnowledgeBase: Newly created knowledge base object.
+            
+        Raises:
+            ModuleException: If knowledge base creation fails due to API problems or configuration errors.
+                
+        Example:
+            >>> knowledge_bases = KnowledgeBases()
+            >>> new_kb = knowledge_bases.create(
+            ...     name="New Knowledge Base",
+            ...     description="A demo knowledge base for testing"
+            ... )
+            >>> print(f"Created knowledge base: {new_kb.id}")
+        """
+        return run_sync(self.acreate(name=name, description=description))

xpander_sdk/modules/knowledge_bases/models/knowledge_bases.py

@@ -0,0 +1,11 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+class KnowledgeBaseType(str, Enum):
+    MANAGED = "managed"
+    EXTERNAL = "external"
+
+class KnowledgeBaseSearchResult(BaseModel):
+    content: str
+    score: float

xpander_sdk/modules/knowledge_bases/sub_modules/knowledge_base.py

@@ -0,0 +1,107 @@
+from typing import List, Optional
+
+from httpx import HTTPStatusError
+from pydantic import BaseModel, Field
+
+from xpander_sdk.consts.api_routes import APIRoute
+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.knowledge_bases.models.knowledge_bases import KnowledgeBaseSearchResult, KnowledgeBaseType
+from xpander_sdk.modules.knowledge_bases.sub_modules.knowledge_base_document_item import KnowledgeBaseDocumentItem
+from xpander_sdk.utils.event_loop import run_sync
+
+class KnowledgeBase(BaseModel):
+    configuration: Optional[Configuration] = None
+    id: str = Field(...)
+    name: str = Field(...)
+    description: Optional[str] = Field(default=None)
+    type: KnowledgeBaseType = Field(...)
+    organization_id: str = Field(...)
+    total_documents: int = Field(default=0)
+
+    async def adelete(self):
+        try:
+            client = APIClient(configuration=self.configuration)
+            await client.make_request(
+                path=APIRoute.DeleteKnowledgeBase.format(knowledge_base_id=self.id),
+                method="DELETE",
+            )
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to delete knowledge base - {str(e)}")
+
+    def delete(self):
+        return run_sync(self.adelete())
+
+    async def alist_documents(self) -> List[KnowledgeBaseDocumentItem]:
+        try:
+            client = APIClient(configuration=self.configuration)
+            docs = await client.make_request(
+                path=APIRoute.ListKnowledgeBaseDocuments.format(knowledge_base_id=self.id),
+                method="GET",
+            )
+            return [KnowledgeBaseDocumentItem(**doc) for doc in docs]
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to list knowledge documents - {str(e)}")
+
+    def list_documents(self) -> List[KnowledgeBaseDocumentItem]:
+        return run_sync(self.alist_documents())
+
+    async def adelete_multiple_documents(self, document_ids: List[str]):
+        try:
+            client = APIClient(configuration=self.configuration)
+            await client.make_request(
+                path=APIRoute.KnowledgeBaseDocumentsCrud.format(knowledge_base_id=self.id),
+                payload=document_ids,
+                method="DELETE",
+            )
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to delete multiple knowledge base documents - {str(e)}")
+
+    def delete_multiple_documents(self, document_ids: List[str]):
+        return run_sync(self.adelete_multiple_documents(document_ids))
+
+    async def aadd_documents(self, document_urls: List[str], sync: Optional[bool] = False) -> List[KnowledgeBaseDocumentItem]:
+        try:
+            client = APIClient(configuration=self.configuration)
+            created_docs = await client.make_request(
+                path=APIRoute.KnowledgeBaseDocumentsCrud.format(knowledge_base_id=self.id),
+                payload=[{"document_url": doc_url, "sync": sync} for doc_url in document_urls],
+                method="POST",
+            )
+            return [KnowledgeBaseDocumentItem(**doc) for doc in created_docs]
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to add knowledge base documents - {str(e)}")
+
+    def add_documents(self, document_urls: List[str], sync: Optional[bool] = False) -> List[KnowledgeBaseDocumentItem]:
+        return run_sync(self.aadd_documents(document_urls, sync))
+
+    async def asearch(self, search_query: str, use_bubble: Optional[bool] = False, bubble_size: Optional[int] = 1000, top_k: Optional[int] = 10) -> List[KnowledgeBaseSearchResult]:
+        try:
+            client = APIClient(configuration=self.configuration)
+            search_results = await client.make_request(
+                path=APIRoute.KnowledgeBaseDocumentsCrud.format(knowledge_base_id=self.id),
+                query={
+                    "search_query": search_query,
+                    "use_bubble": "true" if use_bubble else "false",
+                    "bubble_size": bubble_size,
+                    "top_k": top_k,
+                },
+                method="GET",
+            )
+            return [KnowledgeBaseSearchResult(**res) for res in search_results]
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to search in knowledge base - {str(e)}")
+
+    def search(self, search_query: str, use_bubble: Optional[bool] = False, bubble_size: Optional[int] = 1000, top_k: Optional[int] = 10) -> List[KnowledgeBaseSearchResult]:
+        return run_sync(self.asearch(search_query, use_bubble, bubble_size, top_k))

xpander_sdk/modules/knowledge_bases/sub_modules/knowledge_base_document_item.py

@@ -0,0 +1,40 @@
+from typing import Optional
+
+from httpx import HTTPStatusError
+from pydantic import BaseModel, Field
+
+from xpander_sdk.consts.api_routes import APIRoute
+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.knowledge_bases.models.knowledge_bases import KnowledgeBaseType
+
+class KnowledgeBaseDocumentItem(BaseModel):
+    """
+    Represents a document item within a Knowledge Base.
+
+    Attributes:
+        kb_id (Optional[str]): KB identifier.
+        id (str): Document unique identifier.
+        document_url (str): URL of the document.
+        raw_data (Optional[str]): Raw textual data of the document.
+        local_env (Optional[bool]): Indicates if the document is in a local environment. Defaults to False.
+    """
+    configuration: Optional[Configuration] = None
+    kb_id: Optional[str] = Field(description="KB identifier", default=None)
+    id: Optional[str] = Field(default=None, description="Document unique identifier")
+    document_url: str = Field(..., description="Document URL")
+    raw_data: Optional[str] = Field(description="Raw data (textual)", default=None)
+    
+    async def delete(self):
+        try:
+            client = APIClient(configuration=self.configuration)
+            await client.make_request(
+                path=APIRoute.KnowledgeBaseDocumentsCrud.format(knowledge_base_id=self.kb_id),
+                payload=[self.id],
+                method="DELETE",
+            )
+        except Exception as e:
+            if isinstance(e, HTTPStatusError):
+                raise ModuleException(e.response.status_code, e.response.text)
+            raise ModuleException(500, f"Failed to delete knowledge base document - {str(e)}")