pygeai 0.6.0b11__py3-none-any.whl → 0.6.0b12__py3-none-any.whl

pygeai/core/common/exceptions.py

@@ -7,7 +7,20 @@ class GEAIException(Exception):
 
 class UnknownArgumentError(GEAIException):
     """Raised when an unknown or invalid command/option is provided"""
-    pass
+    
+    def __init__(self, message: str, arg: str = None, available_commands=None, available_options=None):
+        """
+        Initialize an UnknownArgumentError with context.
+        
+        :param message: str - The error message.
+        :param arg: str - The unknown argument that was provided.
+        :param available_commands: list - Available commands for suggestion.
+        :param available_options: list - Available options for suggestion.
+        """
+        super().__init__(message)
+        self.arg = arg
+        self.available_commands = available_commands
+        self.available_options = available_options
 
 
 class MissingRequirementException(GEAIException):
@@ -20,6 +33,56 @@ class WrongArgumentError(GEAIException):
     pass
 
 
+class ValidationError(WrongArgumentError):
+    """
+    Raised when input validation fails with detailed context.
+    
+    Extends WrongArgumentError to provide structured validation errors
+    with field-specific information and examples.
+    """
+    def __init__(
+        self, 
+        message: str, 
+        field: str = None, 
+        expected: str = None,
+        received: str = None,
+        example: str = None
+    ):
+        """
+        Initialize a ValidationError with detailed context.
+
+        :param message: str - The main error message.
+        :param field: str - Name of the field that failed validation.
+        :param expected: str - Description of what was expected.
+        :param received: str - Description of what was received.
+        :param example: str - Example of valid input.
+        """
+        super().__init__(message)
+        self.field = field
+        self.expected = expected
+        self.received = received
+        self.example = example
+    
+    def __str__(self) -> str:
+        """
+        Format the error message with all available context.
+
+        :return: str - Formatted error message with field details.
+        """
+        parts = [super().__str__()]
+        
+        if self.field:
+            parts.append(f"  Field: {self.field}")
+        if self.expected:
+            parts.append(f"  Expected: {self.expected}")
+        if self.received:
+            parts.append(f"  Received: {self.received}")
+        if self.example:
+            parts.append(f"  Example: {self.example}")
+            
+        return "\n".join(parts)
+
+
 class ServerResponseError(GEAIException):
     """Raised when the server returns an error response"""
     pass

pygeai/core/services/rest.py

@@ -15,19 +15,22 @@ FAILED_REQUEST_RESPONSE = ResponseMock(
 
 class ApiService:
     """
-    Generic service for interacting with RESTful APIs.
+    Generic service for interacting with REST APIs.
 
     :param base_url: str - The base URL of the API.
     :param username: str - Username for basic authentication (optional).
     :param password: str - Password for basic authentication (optional).
     :param token: str - Bearer token for authentication (optional).
+    :param project_id: str - Project ID for OAuth authentication (optional, keyword-only).
     """
 
-    def __init__(self, base_url, username: str = None, password: str = None, token: str = None):
+    def __init__(self, base_url, username: str = None, password: str = None, token: str = None, *,
+                 project_id: str = None):
         self._base_url = base_url
         self._username = username
         self._password = password
         self._token = token
+        self._project_id = project_id
 
     @property
     def base_url(self):
@@ -45,6 +48,18 @@ class ApiService:
     def token(self):
         return self._token
 
+    @token.setter
+    def token(self, token: str):
+        self._token = token
+
+    @property
+    def project_id(self):
+        return self._project_id
+
+    @project_id.setter
+    def project_id(self, project_id: str):
+        self._project_id = project_id
+
     def get(self, endpoint: str, params: dict = None, headers: dict = None, verify: bool = True):
         """
         Sends a GET request to the specified API endpoint.
@@ -403,4 +418,7 @@ class ApiService:
             if "Authorization" not in headers:
                 headers["Authorization"] = f"Bearer {self.token}"
 
+        if self.project_id and "ProjectId" not in headers:
+            headers["ProjectId"] = self.project_id
+
         return headers

pygeai/evaluation/clients.py

@@ -7,11 +7,13 @@ from pygeai.core.utils.validators import validate_status_code
 
 class EvaluationClient(BaseClient):
 
-    def __init__(self, api_key: str = None, base_url: str = None, alias: str = "default", eval_url: str = None):
-        super().__init__(api_key, base_url, alias)
+    def __init__(self, api_key: str = None, base_url: str = None, alias: str = "default", eval_url: str = None, *,
+                 access_token: str = None, project_id: str = None):
+        super().__init__(api_key, base_url, alias, access_token=access_token, project_id=project_id)
         eval_url = self.session.eval_url if not eval_url else eval_url
         if not eval_url:
             raise MissingRequirementException("EVAL URL must be defined in order to use the Evaluation module.")
 
         self.session.eval_url = eval_url
-        self.api_service = ApiService(base_url=self.session.eval_url, token=self.session.api_key)
+        token = self.session.access_token if self.session.access_token else self.session.api_key
+        self.api_service = ApiService(base_url=self.session.eval_url, token=token, project_id=self.session.project_id)

pygeai/lab/agents/clients.py

@@ -5,7 +5,7 @@ from pygeai.core.common.exceptions import MissingRequirementException, InvalidAP
 from pygeai.core.utils.validators import validate_status_code
 from pygeai.core.utils.parsers import parse_json_response
 from pygeai.lab.agents.endpoints import CREATE_AGENT_V2, LIST_AGENTS_V2, GET_AGENT_V2, CREATE_SHARING_LINK_V2, \
-    PUBLISH_AGENT_REVISION_V2, DELETE_AGENT_V2, UPDATE_AGENT_V2, UPSERT_AGENT_V2, EXPORT_AGENT_V4, IMPORT_AGENT_V4
+    PUBLISH_AGENT_REVISION_V2, DELETE_AGENT_V2, UPDATE_AGENT_V2, UPSERT_AGENT_V2, EXPORT_AGENT_V2, IMPORT_AGENT_V2
 from pygeai.lab.constants import VALID_ACCESS_SCOPES
 from pygeai.lab.clients import AILabClient
 
@@ -380,7 +380,7 @@ class AgentClient(AILabClient):
         if not agent_id:
             raise MissingRequirementException("agent_id must be specified in order to export the agent")
 
-        endpoint = EXPORT_AGENT_V4.format(agentId=agent_id)
+        endpoint = EXPORT_AGENT_V2.format(agentId=agent_id)
         headers = {
             "Authorization": self.api_service.token,
             "ProjectId": self.project_id
@@ -410,7 +410,7 @@ class AgentClient(AILabClient):
         if not data:
             raise MissingRequirementException("data for spec must be specified in order to import the agent")
 
-        endpoint = IMPORT_AGENT_V4
+        endpoint = IMPORT_AGENT_V2
         headers = {
             "Authorization": self.api_service.token,
             "ProjectId": self.project_id

pygeai/lab/agents/endpoints.py

@@ -8,5 +8,5 @@ UPDATE_AGENT_V2 = "v2/agents/{agentId}"  # PUT -> Update agent
 UPSERT_AGENT_V2 = "v2/agents/{agentId}/upsert"  # PUT -> Update or Insert agent
 EXPORT_AGENT_V2 = "v2/agents/{agentId}/export"  # GET -> Export agent
 IMPORT_AGENT_V2 = "v2/agents/import"  # POST -> Import agent
-EXPORT_AGENT_V4 = "v4/agents/{agentId}/export"  # GET -> Export agent
-IMPORT_AGENT_V4 = "v4/agents/import"  # POST -> Import agent
+# EXPORT_AGENT_V4 = "v4/agents/{agentId}/export"  # GET -> Export agent
+# IMPORT_AGENT_V4 = "v4/agents/import"  # POST -> Import agent

pygeai/lab/agents/mappers.py

@@ -1,7 +1,7 @@
 from typing import Optional, List
 
 from pygeai.lab.models import Agent, AgentList, SharingLink, AgentData, Prompt, PromptOutput, PromptExample, LlmConfig, \
-    Sampling, ModelList, Model, ResourcePoolList, ResourcePool, ResourcePoolAgent, ResourcePoolTool
+    Sampling, ModelList, Model, ResourcePoolList, ResourcePool, ResourcePoolAgent, ResourcePoolTool, Permission, Property
 
 
 class AgentMapper:
@@ -38,6 +38,8 @@ class AgentMapper:
         :return: Agent - The mapped `Agent` object.
         """
         agent_data_data = data.get("agentData")
+        permissions_data = data.get("permissions")
+        effective_permissions_data = data.get("effectivePermissions")
         return Agent(
             id=data.get("id"),
             status=data.get("status"),
@@ -51,6 +53,9 @@ class AgentMapper:
             is_readonly=data.get("isReadonly"),
             revision=data.get("revision"),
             version=data.get("version"),
+            sharing_scope=data.get("sharingScope"),
+            permissions=cls._map_to_permission(permissions_data) if permissions_data else None,
+            effective_permissions=cls._map_to_permission(effective_permissions_data) if effective_permissions_data else None,
             agent_data=cls._map_agent_data(agent_data_data) if agent_data_data else None
         )
 
@@ -67,12 +72,14 @@ class AgentMapper:
         models_list = data.get("models")
         strategy_name = data.get("strategyName")
         resource_pool_list = data.get("resourcePools")
+        properties_list = data.get("properties")
         return AgentData(
             prompt=cls._map_to_prompt(prompt_data) if prompt_data else None,
             llm_config=cls._map_to_llm_config(llm_config_data) if llm_config_data else None,
             strategy_name=strategy_name,
             models=cls._map_to_model_list(models_list) if models_list else None,
-            resource_pools=cls._map_to_resource_pool_list(resource_pool_list) if resource_pool_list else None
+            resource_pools=cls._map_to_resource_pool_list(resource_pool_list) if resource_pool_list else None,
+            properties=cls._map_to_property_list(properties_list) if properties_list else None
         )
 
     @classmethod
@@ -269,3 +276,44 @@ class AgentMapper:
             api_token=data.get('apiToken'),
             shared_link=data.get('sharedLink'),
         )
+
+    @classmethod
+    def _map_to_permission(cls, data: dict) -> Permission:
+        """
+        Maps a dictionary to a `Permission` object.
+
+        :param data: dict - The dictionary containing permission details.
+        :return: Permission - The mapped `Permission` object, or None if data is None.
+        """
+        if data is None:
+            return None
+        return Permission(
+            chat_sharing=data.get('chatSharing'),
+            external_execution=data.get('externalExecution')
+        )
+
+    @classmethod
+    def _map_to_property_list(cls, data: List[dict]) -> List[Property]:
+        """
+        Maps a list of dictionaries to a list of `Property` objects.
+
+        :param data: List[dict] - The list of dictionaries containing property details.
+        :return: List[Property] - The mapped list of `Property` objects, or None if data is None.
+        """
+        if data is None:
+            return None
+        return [cls._map_to_property(prop) for prop in data]
+
+    @classmethod
+    def _map_to_property(cls, data: dict) -> Property:
+        """
+        Maps a dictionary to a `Property` object.
+
+        :param data: dict - The dictionary containing property details.
+        :return: Property - The mapped `Property` object.
+        """
+        return Property(
+            data_type=data.get('dataType'),
+            key=data.get('key'),
+            value=data.get('value')
+        )

pygeai/lab/clients.py

@@ -7,9 +7,12 @@ from pygeai.core.utils.validators import validate_status_code
 
 class AILabClient(BaseClient):
 
-    def __init__(self, api_key: str = None, base_url: str = None, alias: str = None, project_id: str = None):
-        super().__init__(api_key, base_url, alias)
+    def __init__(self, api_key: str = None, base_url: str = None, alias: str = None, *,
+                 access_token: str = None, project_id: str = None):
+        super().__init__(api_key, base_url, alias, access_token=access_token, project_id=project_id)
         self.project_id = project_id if project_id else self.__get_project_id(api_key, base_url, alias)
+        if self.project_id and not self.api_service.project_id:
+            self.api_service.project_id = self.project_id
 
     def __get_project_id(self, api_key: str = None, base_url: str = None, alias: str = None):
         response = None

pygeai/lab/managers.py

@@ -91,7 +91,7 @@ class AILabManager:
             agent_data_prompt=agent.agent_data.prompt.to_dict() if agent.agent_data is not None else None,
             agent_data_strategy_name=agent.agent_data.strategy_name if agent.agent_data is not None else None,
             agent_data_llm_config=agent.agent_data.llm_config.to_dict() if agent.agent_data is not None else None,
-            agent_data_models=agent.agent_data.models.to_dict() if agent.agent_data is not None else None,
+            agent_data_models=agent.agent_data.models.to_dict() if agent.agent_data and agent.agent_data.models else None,
             agent_data_resource_pools=agent.agent_data.resource_pools.to_dict() if agent.agent_data and agent.agent_data.resource_pools else None,
             automatic_publish=automatic_publish
         )
@@ -137,8 +137,9 @@ class AILabManager:
             description=agent.description,
             agent_data_prompt=agent.agent_data.prompt.to_dict() if agent.agent_data is not None else None,
             agent_data_llm_config=agent.agent_data.llm_config.to_dict() if agent.agent_data is not None else None,
-            agent_data_strategy_name=agent.agent_data.strategy_name if agent.agent_data is not None else None,
-            agent_data_models=agent.agent_data.models.to_dict() if agent.agent_data is not None else None,
+            agent_data_strategy_name=agent.agent_data.strategy_name if agent.agent_data and agent.agent_data.strategy_name else None,
+            agent_data_models=agent.agent_data.models.to_dict() if agent.agent_data and agent.agent_data.models else None,
+            agent_data_resource_pools=agent.agent_data.resource_pools.to_dict() if agent.agent_data and agent.agent_data.resource_pools else None,
             automatic_publish=automatic_publish,
             upsert=upsert
         )
@@ -264,8 +265,7 @@ class AILabManager:
             logger.error(f"Error received while deleting agent: {error}")
             raise APIError(f"Error received while deleting agent: {error}")
 
-        response_data = response_data if response_data else "Agent deleted successfully"
-        result = ResponseMapper.map_to_empty_response(response_data)
+        result = ResponseMapper.map_to_empty_response(response_data or "Agent deleted successfully")
         return result
 
     def create_tool(
@@ -431,8 +431,7 @@ class AILabManager:
             logger.error(f"Error received while deleting tool: {error}")
             raise APIError(f"Error received while deleting tool: {error}")
 
-        response_data = response_data if response_data else "Tool deleted successfully"
-        result = ResponseMapper.map_to_empty_response(response_data)
+        result = ResponseMapper.map_to_empty_response(response_data or "Tool deleted successfully")
         return result
 
     def list_tools(
@@ -1518,8 +1517,7 @@ class AILabManager:
             logger.error(f"Error received while deleting knowledge base: {error}")
             raise APIError(f"Error received while deleting knowledge base: {error}")
 
-        response_data = response_data if response_data else "Knowledge base deleted successfully"
-        result = ResponseMapper.map_to_empty_response(response_data)
+        result = ResponseMapper.map_to_empty_response(response_data or "Knowledge base deleted successfully")
         return result
 
     def list_jobs(

pygeai/lab/models.py

@@ -385,6 +385,38 @@ class ResourcePoolList(CustomBaseModel):
         self.resource_pools.append(item)
 
 
+class Permission(CustomBaseModel):
+    """
+    Represents permission settings for an agent.
+
+    :param chat_sharing: Literal["none", "organization", "project"] - Chat sharing permission level.
+    :param external_execution: Literal["none", "organization", "project"] - External execution permission level.
+    """
+    chat_sharing: Optional[Literal["none", "organization", "project"]] = Field(None, alias="chatSharing", description="Chat sharing permission level")
+    external_execution: Optional[Literal["none", "organization", "project"]] = Field(None, alias="externalExecution", description="External execution permission level")
+
+    def to_dict(self):
+        """Convert Permission to dictionary with API aliases."""
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
+class Property(CustomBaseModel):
+    """
+    Represents a property key-value pair with data type.
+
+    :param data_type: str - Data type of the property (e.g., "String", "Number", "Boolean").
+    :param key: str - Property key identifier.
+    :param value: str - Property value.
+    """
+    data_type: str = Field(..., alias="dataType", description="Data type of the property")
+    key: str = Field(..., alias="key", description="Property key identifier")
+    value: str = Field(..., alias="value", description="Property value")
+
+    def to_dict(self):
+        """Convert Property to dictionary with API aliases."""
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
 class AgentData(CustomBaseModel):
     """
     Represents the detailed configuration data for an agent.
@@ -400,6 +432,7 @@ class AgentData(CustomBaseModel):
     strategy_name: Optional[str] = Field("Dynamic Prompting", alias="strategyName")
     models: Optional[Union[ModelList, List[Model]]] = Field(None, alias="models")
     resource_pools: Optional[ResourcePoolList] = Field(None, alias="resourcePools", description="List of resource pools organizing tools and helper agents")
+    properties: Optional[List[Property]] = Field(None, alias="properties", description="List of agent properties")
 
     @field_validator("prompt", mode="before")
     @classmethod
@@ -418,6 +451,8 @@ class AgentData(CustomBaseModel):
     @field_validator("models", mode="before")
     @classmethod
     def normalize_models(cls, value):
+        if value is None:
+            return None
         if isinstance(value, ModelList):
             return value
         elif isinstance(value, list):
@@ -433,6 +468,13 @@ class AgentData(CustomBaseModel):
             return ResourcePoolList(resource_pools=[ResourcePool.model_validate(item) if isinstance(item, dict) else item for item in value])
         return value
 
+    @field_validator("properties", mode="before")
+    @classmethod
+    def normalize_properties(cls, value):
+        if isinstance(value, list):
+            return [Property.model_validate(item) if isinstance(item, dict) else item for item in value]
+        return value
+
     @model_validator(mode="after")
     def validate_resource_pools_unique_names(self):
         if self.resource_pools:
@@ -451,8 +493,10 @@ class AgentData(CustomBaseModel):
         result = {
             "prompt": self.prompt.to_dict(),
             "llmConfig": self.llm_config.to_dict(),
-            "models": self.models.to_dict(),
-            "resourcePools": [pool.to_dict() for pool in self.resource_pools] if self.resource_pools else None
+            "strategyName": self.strategy_name,
+            "models": self.models.to_dict() if self.models else None,
+            "resourcePools": [pool.to_dict() for pool in self.resource_pools] if self.resource_pools else None,
+            "properties": [prop.to_dict() for prop in self.properties] if self.properties else None
         }
         return {k: v for k, v in result.items() if v is not None}
 
@@ -490,6 +534,9 @@ class Agent(CustomBaseModel):
     is_readonly: Optional[bool] = Field(False, alias="isReadonly")
     revision: Optional[int] = Field(None, alias="revision")
     version: Optional[Union[int | float]] = Field(None, alias="version")
+    sharing_scope: Optional[str] = Field(None, alias="sharingScope", description="Sharing scope of the agent")
+    permissions: Optional[Permission] = Field(None, alias="permissions", description="Permission settings")
+    effective_permissions: Optional[Permission] = Field(None, alias="effectivePermissions", description="Effective permission settings")
     agent_data: Optional[AgentData] = Field(None, alias="agentData")
 
     @field_validator("name")
@@ -528,6 +575,20 @@ class Agent(CustomBaseModel):
             return AgentData.model_validate(value)
         return value
 
+    @field_validator("permissions", mode="before")
+    @classmethod
+    def normalize_permissions(cls, value):
+        if isinstance(value, dict):
+            return Permission.model_validate(value)
+        return value
+
+    @field_validator("effective_permissions", mode="before")
+    @classmethod
+    def normalize_effective_permissions(cls, value):
+        if isinstance(value, dict):
+            return Permission.model_validate(value)
+        return value
+
     @model_validator(mode="after")
     def check_public_name(self):
         """
@@ -553,6 +614,9 @@ class Agent(CustomBaseModel):
             "isReadonly": self.is_readonly,
             "revision": self.revision,
             "version": self.version,
+            "sharingScope": self.sharing_scope,
+            "permissions": self.permissions.to_dict() if self.permissions else None,
+            "effectivePermissions": self.effective_permissions.to_dict() if self.effective_permissions else None,
             "agentData": self.agent_data.to_dict() if self.agent_data else None
         }
         return {k: v for k, v in result.items() if v is not None}
@@ -918,6 +982,7 @@ class KnowledgeBase(CustomBaseModel):
     artifact_type_name: Optional[List[str]] = Field(None, alias="artifactTypeName", description="List of artifact type names")
     artifacts: Optional[List[str]] = Field(None, description="List of artifact identifiers")
     metadata: Optional[List[str]] = Field(None, description="List of metadata identifiers")
+    created_at: Optional[str] = Field(None, alias="createdAt", description="Timestamp when the knowledge base was created")
 
     @field_validator("artifacts")
     @classmethod
@@ -1269,6 +1334,7 @@ class Task(CustomBaseModel):
     :param artifact_types: Optional[List[dict]] - List of artifact types with 'name', 'description', 'isRequired', 'usageType', and 'artifactVariableKey'.
     :param is_draft: Optional[bool] - Whether the task is in draft mode.
     :param revision: Optional[int] - Revision number of the task.
+    :param version: Optional[int] - Version number of the task.
     :param status: Optional[str] - Current status of the task (e.g., 'active').
     """
     name: str = Field(..., description="Name of the task")
@@ -1279,6 +1345,7 @@ class Task(CustomBaseModel):
     artifact_types: Optional[Union[List[Dict[str, Any]], List[ArtifactType], ArtifactTypeList]] = Field(None, alias="artifactTypes", description="List of artifact types for the task")
     is_draft: Optional[bool] = Field(None, alias="isDraft", description="Whether the task is a draft")
     revision: Optional[int] = Field(None, description="Revision number of the task")
+    version: Optional[int] = Field(None, description="Version number of the task")
     status: Optional[str] = Field(None, description="Status of the task (e.g., 'active')")
 
     @field_validator("name")
@@ -1367,6 +1434,7 @@ class Task(CustomBaseModel):
             "artifactTypes": self.artifact_types.to_dict() if self.artifact_types else None,
             "isDraft": self.is_draft,
             "revision": self.revision,
+            "version": self.version,
             "status": self.status
         }
         return {k: v for k, v in result.items() if v is not None}