pygeai 0.1.6__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/core/common/decorators.py

@@ -0,0 +1,44 @@
+import functools
+import sys
+import time
+
+from pygeai.core.common.exceptions import ServerResponseError
+
+
+def measure_execution_time(func):
+    """
+    Measure execution time of method or function.
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        sys.stdout.write(f"Measuring execution time for: {func.__name__}")
+        try:
+            start_time = time.time()
+            result = func(*args, **kwargs)
+            finish_time = time.time()
+            time_difference = finish_time - start_time
+            execution_time = round(time_difference, 6)
+        except Exception as e:
+            sys.stdout.write(f"Error measuring execution time: {e}")
+        else:
+            sys.stdout.write(f"Function {func.__name__} executed in {execution_time} s")
+            return result
+
+    return wrapper
+
+
+def handler_server_error(func):
+    """
+    Intercepts server errors
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        result = func(*args, **kwargs)
+        if "error" in result:
+            raise ServerResponseError(
+                f"There was an error communicating with the server: {result.get('error')}"
+            )
+
+        return result
+
+    return wrapper

pygeai/core/common/exceptions.py

@@ -6,19 +6,119 @@ class GEAIException(Exception):
 
 
 class UnknownArgumentError(GEAIException):
-    """Argument provided is not valid"""
-    pass
+    """Raised when an unknown or invalid command/option is provided"""
+    
+    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):
-    """Requirement not available"""
+    """Raised when a required parameter or argument is missing"""
     pass
 
 
 class WrongArgumentError(GEAIException):
-    """Wrongly formatted arguments"""
+    """Raised when arguments are incorrectly formatted or invalid"""
+    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
+
+
+class APIError(GEAIException):
+    """Raised when an API request fails"""
+    pass
+
+
+class InvalidPathException(GEAIException):
+    """Raised when a file or directory path is invalid or not found"""
     pass
 
 
+class InvalidJSONException(GEAIException):
+    """Raised when JSON data cannot be parsed or is malformed"""
+    pass
+
 
+class InvalidAPIResponseException(GEAIException):
+    """Raised when the API response format is unexpected or invalid"""
+    pass
+
+
+class InvalidResponseException(GEAIException):
+    """Raised when a response cannot be retrieved or processed"""
+    pass
+
+
+class InvalidAgentException(GEAIException):
+    """Raised when an agent cannot be retrieved, validated, or is misconfigured"""
+    pass
+
+
+class APIResponseError(GEAIException):
+    """Raised when there is an error in the API response"""
+    pass
 

pygeai/core/embeddings/__init__.py

@@ -0,0 +1,19 @@
+from pygeai.core.embeddings.clients import EmbeddingsClient
+from pygeai.core.embeddings.managers import EmbeddingsManager
+from pygeai.core.embeddings.models import EmbeddingConfiguration
+from pygeai.core.embeddings.responses import (
+    EmbeddingResponse,
+    EmbeddingData,
+    UsageInfo,
+    TokenDetails
+)
+
+__all__ = [
+    'EmbeddingsClient',
+    'EmbeddingsManager',
+    'EmbeddingConfiguration',
+    'EmbeddingResponse',
+    'EmbeddingData',
+    'UsageInfo',
+    'TokenDetails'
+]

pygeai/core/embeddings/clients.py

@@ -0,0 +1,93 @@
+
+from pygeai import logger
+from pygeai.core.base.clients import BaseClient
+from pygeai.core.common.exceptions import InvalidAPIResponseException, APIResponseError
+from pygeai.core.embeddings.endpoints import GENERATE_EMBEDDINGS
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
+
+
+class EmbeddingsClient(BaseClient):
+
+    def generate_embeddings(
+            self,
+            input_list: list,
+            model: str,
+            encoding_format: str = None,
+            dimensions: int = None,
+            user: str = None,
+            input_type: str = None,
+            timeout: int = None,
+            cache: bool = False
+    ) -> dict:
+        """
+        Generates an embedding vector representing the provided input(s) using the specified model.
+
+        This method calls the API to create a vector representation of the input(s), which can be used
+        in machine learning models and algorithms. The request is sent to the embeddings API endpoint.
+
+        :param input_list: list - A list of strings representing the input(s) to embed.
+                                 Each input must not exceed the maximum input tokens for the model
+                                 and cannot be an empty string.
+        :param model: str - The provider/modelId to use for generating embeddings.
+        :param encoding_format: str, optional - The format for the returned embeddings, either 'float'
+                                               (default) or 'base64'. Only supported by OpenAI.
+        :param dimensions: int, optional - The number of dimensions for the resulting output embeddings.
+                                            Only supported in text-embedding-3* and later models.
+        :param user: str, optional - A unique identifier representing the end-user. Specific to OpenAI.
+        :param input_type: str, optional - Defines how the input data will be used when generating
+                                            embeddings. Check if the selected embeddings model supports this option.
+        :param timeout: int, optional - The maximum time, in seconds, to wait for the API to respond.
+                                        Defaults to 600 seconds.
+        :param cache: bool, optional - Whether to enable caching for the embeddings. Defaults to False.
+
+        :return: dict - A dictionary containing the embedding results, including the model used, the generated
+                        embedding vectors, and usage statistics.
+        :raises ValueError: If validation fails for input parameters.
+        """
+        if not input_list or len(input_list) == 0:
+            raise ValueError("input_list cannot be empty")
+        
+        for idx, inp in enumerate(input_list):
+            if not inp or (isinstance(inp, str) and inp.strip() == ""):
+                raise ValueError(f"Input at index {idx} cannot be empty")
+        
+        if encoding_format is not None and encoding_format not in ['float', 'base64']:
+            raise ValueError("encoding_format must be either 'float' or 'base64'")
+        
+        if dimensions is not None and dimensions <= 0:
+            raise ValueError("dimensions must be a positive integer")
+        
+        data = {
+            'model': model,
+            'input': input_list,
+        }
+        if encoding_format is not None:
+            data["encoding_format"] = encoding_format
+
+        if dimensions is not None:
+            data["dimensions"] = dimensions
+
+        if user is not None:
+            data["user"] = user
+
+        if input_type is not None:
+            data["input_type"] = input_type
+
+        if timeout is not None:
+            data["timeout"] = timeout
+
+        logger.debug(f"Generating embeddings with data: {data}")
+
+        headers = {}
+        if cache:
+            headers['X-Saia-Cache-Enabled'] = "true"
+
+        response = self.api_service.post(
+            endpoint=GENERATE_EMBEDDINGS,
+            data=data,
+            headers=headers
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "generate embeddings")
+        

pygeai/core/embeddings/endpoints.py

@@ -0,0 +1 @@
+GENERATE_EMBEDDINGS = "/embeddings"  # POST -> Creates an embedding vector representing the input

pygeai/core/embeddings/managers.py

@@ -0,0 +1,62 @@
+from pygeai import logger
+from pygeai.core.base.mappers import ErrorMapper
+from pygeai.core.common.exceptions import APIError
+from pygeai.core.embeddings.clients import EmbeddingsClient
+from pygeai.core.embeddings.mappers import EmbeddingsResponseMapper
+from pygeai.core.embeddings.models import EmbeddingConfiguration
+from pygeai.core.embeddings.responses import EmbeddingResponse
+from pygeai.core.handlers import ErrorHandler
+
+
+class EmbeddingsManager:
+
+    def __init__(self, api_key: str = None, base_url: str = None, alias: str = None):
+        self.__client = EmbeddingsClient(api_key, base_url, alias)
+
+    def generate_embeddings(
+            self,
+            configuration: EmbeddingConfiguration
+    ) -> EmbeddingResponse:
+        """
+        Generates an embedding vector representing the provided input(s) using the specified model.
+
+        This method calls the API to create a vector representation of the input(s), which can be used
+        in machine learning models and algorithms. The request is sent to the embeddings API endpoint.
+
+        :param configuration: EmbeddingConfiguration - An instance containing the configuration for generating
+                                                      embeddings, including:
+            - inputs: list - A list of strings representing the input(s) to embed. Each input must not
+                             exceed the maximum input tokens for the model and cannot be an empty string.
+            - model: str - The provider/modelId to use for generating embeddings.
+            - encoding_format: str, optional - The format for the returned embeddings, either 'float'
+                                                  (default) or 'base64'. Only supported by OpenAI.
+            - dimensions: int, optional - The number of dimensions for the resulting output embeddings.
+                                           Only supported in text-embedding-3* and later models.
+            - user: str, optional - A unique identifier representing the end-user. Specific to OpenAI.
+            - input_type: str, optional - Defines how the input data will be used when generating
+                                           embeddings. Check if the selected embeddings model supports this option.
+            - timeout: int, optional - The maximum time, in seconds, to wait for the API to respond.
+                                       Defaults to 600 seconds.
+            - cache: bool, optional - Whether to enable caching for the embeddings. Defaults to False.
+
+        :return: EmbeddingResponse - A response object containing the generated embeddings and usage information.
+        :raises APIError - If the API returns errors.
+        """
+        response_data = self.__client.generate_embeddings(
+            input_list=configuration.inputs,
+            model=configuration.model,
+            encoding_format=configuration.encoding_format,
+            dimensions=configuration.dimensions,
+            user=configuration.user,
+            input_type=configuration.input_type,
+            timeout=configuration.timeout,
+            cache=configuration.cache,
+        )
+
+        if ErrorHandler.has_errors(response_data):
+            error = ErrorHandler.extract_error(response_data)
+            logger.error(f"Error received while generating embeddings: {error}")
+            raise APIError(f"Error received while generating embeddings: {error}")
+
+        result = EmbeddingsResponseMapper.map_to_embedding_response(response_data)
+        return result

pygeai/core/embeddings/mappers.py

@@ -0,0 +1,52 @@
+from pygeai.core.embeddings.responses import EmbeddingResponse, EmbeddingData, UsageInfo, TokenDetails
+
+
+class EmbeddingsResponseMapper:
+
+    @classmethod
+    def map_to_embedding_response(cls, data: dict) -> EmbeddingResponse:
+        embedding_data_list = cls.map_to_embedding_data_list(data.get('data', []))
+        usage_info = cls.map_to_usage_info(data.get('usage', {}))
+
+        return EmbeddingResponse(
+            data=embedding_data_list,
+            usage=usage_info,
+            model=data.get('model', ''),
+            object=data.get('object', '')
+        )
+
+    @classmethod
+    def map_to_embedding_data_list(cls, data: list) -> list[EmbeddingData]:
+        embedding_data_list = []
+        for item in data:
+            embedding_data = EmbeddingData(
+                index=item.get('index', 0),
+                embedding=item.get('embedding', []),
+                object=item.get('object', '')
+            )
+            embedding_data_list.append(embedding_data)
+        return embedding_data_list
+
+    @classmethod
+    def map_to_usage_info(cls, data: dict) -> UsageInfo:
+        completion_tokens_details_data = data.get('completion_tokens_details')
+        prompt_tokens_details_data = data.get('prompt_tokens_details')
+        
+        return UsageInfo(
+            prompt_tokens=data.get('prompt_tokens', 0),
+            total_cost=data.get('total_cost', 0.0),
+            total_tokens=data.get('total_tokens', 0),
+            currency=data.get('currency', ''),
+            prompt_cost=data.get('prompt_cost', 0.0),
+            completion_tokens_details=cls._parse_token_details(completion_tokens_details_data),
+            prompt_tokens_details=cls._parse_token_details(prompt_tokens_details_data)
+        )
+
+    @classmethod
+    def _parse_token_details(cls, data: dict) -> TokenDetails | None:
+        if data is None:
+            return None
+        return TokenDetails(
+            reasoning_tokens=data.get('reasoning_tokens'),
+            cached_tokens=data.get('cached_tokens')
+        )

pygeai/core/embeddings/models.py

@@ -0,0 +1,14 @@
+from typing import List, Optional
+
+from pydantic.main import BaseModel
+
+
+class EmbeddingConfiguration(BaseModel):
+    inputs: List[str]
+    model: str
+    encoding_format: Optional[str] = None
+    dimensions: Optional[int] = None
+    user: Optional[str] = None
+    input_type: Optional[str] = None
+    timeout: Optional[int] = None
+    cache: Optional[bool] = False

pygeai/core/embeddings/responses.py

@@ -0,0 +1,31 @@
+from typing import List, Union, Optional
+
+from pydantic.main import BaseModel
+
+
+class TokenDetails(BaseModel):
+    reasoning_tokens: Optional[int] = None
+    cached_tokens: Optional[int] = None
+
+
+class EmbeddingData(BaseModel):
+    index: int
+    embedding: Union[List[float], str]
+    object: str
+
+
+class UsageInfo(BaseModel):
+    prompt_tokens: int
+    total_cost: float
+    total_tokens: int
+    currency: str
+    prompt_cost: float
+    completion_tokens_details: Optional[TokenDetails] = None
+    prompt_tokens_details: Optional[TokenDetails] = None
+
+
+class EmbeddingResponse(BaseModel):
+    data: List[EmbeddingData]
+    usage: UsageInfo
+    model: str
+    object: str

pygeai/core/feedback/clients.py

@@ -0,0 +1,50 @@
+from typing import Any, Union
+
+from pygeai import logger
+from pygeai.core.base.clients import BaseClient
+from pygeai.core.common.exceptions import InvalidAPIResponseException
+from pygeai.core.feedback.endpoints import SEND_FEEDBACK_V1
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
+
+
+class FeedbackClient(BaseClient):
+
+    def send_feedback(
+            self,
+            request_id: str,
+            origin: str = "user-feedback",
+            answer_score: int = 1,
+            comments: str = None
+    ) -> dict:
+        """
+        Sends feedback for an assistant's response.
+
+        This method submits user feedback to the Feedback API, associating it with a specific request.
+        The feedback includes an origin identifier, a score indicating the response quality, and an optional comment.
+
+        :param request_id: str - The request associated with a user's execution.
+        :param origin: str - The origin of the feedback. Should be set to "user-feedback".
+        :param answer_score: int - The score for the response.
+           - 1: Good
+           - 2: Bad
+        :param comments: str, optional - Additional feedback comments. Defaults to None.
+        :return: dict - The parsed JSON response from the API. The expected response is an empty JSON object ({}).
+        """
+        data = {
+            "origin": origin,
+            "answerScore": answer_score,
+        }
+        if comments:
+            data["comments"] = comments
+
+        logger.debug(f"Providing feedback with data: {data}")
+
+        endpoint = SEND_FEEDBACK_V1.format(requestId=request_id)
+        response = self.api_service.post(
+            endpoint=endpoint,
+            data=data
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "send feedback. JSON parsing error")
+

pygeai/core/feedback/endpoints.py

@@ -0,0 +1 @@
+SEND_FEEDBACK_V1 = "v1/feedback/request/{requestId}"     # POST -> Add feedback to a request associated with a user's execution; note the requestId parameters are returned on every assistant reply.

pygeai/core/feedback/models.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, Field
+
+from pygeai.core import CustomBaseModel
+
+
+class FeedbackRequest(CustomBaseModel):
+    request_id: str = Field(..., alias="requestId")
+    origin: str = Field("user-feedback", alias="origin")
+    answer_score: int = Field(..., alias="answerScore")
+    comments: str = Field(None, alias="comments")

pygeai/core/files/clients.py

@@ -0,0 +1,156 @@
+import json
+from json import JSONDecodeError
+from pathlib import Path
+
+from pygeai import logger
+from pygeai.core.base.clients import BaseClient
+from pygeai.core.common.exceptions import InvalidAPIResponseException
+from pygeai.core.files.endpoints import UPLOAD_FILE_V1, GET_FILE_V1, DELETE_FILE_V1, GET_FILE_CONTENT_V1, \
+    GET_ALL_FILES_V1
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
+
+
+class FileClient(BaseClient):
+
+    def upload_file(
+        self,
+        file_path: str,
+        organization_id: str,
+        project_id: str,
+        folder: str = None,
+        file_name: str = None
+    ) -> dict:
+        """
+        Uploads a file to the system.
+
+        :param file_path: str - Path to the file to be uploaded.
+        :param organization_id: str - The organization ID.
+        :param project_id: str - The project ID.
+        :param folder: str, optional - Destination folder (default is None, which means temporary storage).
+        :param file_name: str, optional - Custom file name (defaults to the uploaded file's name).
+
+        :return: dict - API response containing file ID and URL.
+        """
+        file_path = Path(file_path)
+        if not file_path.is_file():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        headers = {
+            "organizationId": organization_id,
+            "projectId": project_id,
+        }
+        if file_name:
+            headers["fileName"] = file_name
+        if folder:
+            headers["folder"] = folder
+
+        files = {"file": file_path.open("rb")}
+
+        logger.debug(f"Uploading file {file_name}")
+
+        try:
+            response = self.api_service.post_files_multipart(
+                endpoint=UPLOAD_FILE_V1,
+                headers=headers,
+                files=files
+            )
+            validate_status_code(response)
+            return parse_json_response(response, "upload file in project", file_name=file_name, project_id=project_id)
+
+        finally:
+            files["file"].close()
+
+    def get_file(self, organization: str, project: str, file_id: str) -> dict:
+        """
+        Retrieves details of a specific file by its ID.
+
+        :param organization: str - The ID of the organization that owns the file.
+        :param project: str - The ID of the project associated with the file.
+        :param file_id: str - The unique identifier of the file.
+        :return: dict - The file metadata as a dictionary.
+        """
+        endpoint = GET_FILE_V1.format(fileId=file_id)
+        response = self.api_service.get(
+            endpoint=endpoint,
+            params={
+                "organization": organization,
+                "project": project
+            }
+        )
+        logger.debug(f"Retrieving file details for id {file_id}")
+        validate_status_code(response)
+        return parse_json_response(response, "retrieve file details for id in project", file_id=file_id, project=project)
+
+    def delete_file(self, organization: str, project: str, file_id: str) -> dict:
+        """
+        Deletes a file by its ID.
+
+        :param organization: str - The ID of the organization that owns the file.
+        :param project: str - The ID of the project associated with the file.
+        :param file_id: str - The unique identifier of the file.
+        :return: dict - Response indicating the success or failure of the deletion.
+        """
+        endpoint = DELETE_FILE_V1.format(fileId=file_id)
+        headers = {
+            "Accept": "application/json",
+        }
+
+        logger.debug(f"Deleting file with id {file_id}")
+
+        response = self.api_service.delete(
+            endpoint=endpoint,
+            headers=headers,
+            data={
+                "organization": organization,
+                "project": project
+            }
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "delete file with id in project", file_id=file_id, project=project)
+
+    def get_file_content(self, organization: str, project: str, file_id: str) -> bytes:
+        """
+        Retrieves the raw content of a file by its ID.
+
+        :param organization: str - The ID of the organization that owns the file.
+        :param project: str - The ID of the project associated with the file.
+        :param file_id: str - The unique identifier of the file.
+        :return: bytes - The file content in binary format.
+        """
+        endpoint = GET_FILE_CONTENT_V1.format(fileId=file_id)
+
+        logger.debug(f"Retrieving raw content of file with id {file_id}")
+
+        response = self.api_service.get(
+            endpoint=endpoint,
+            params={
+                "organization": organization,
+                "project": project
+            }
+        )
+        return response.content
+
+    def get_file_list(
+            self,
+            organization: str,
+            project: str
+    ) -> dict:
+        """
+        Retrieves a list of all files associated with a given organization and project.
+
+        :param organization: str - The ID of the organization.
+        :param project: str - The ID of the project.
+        :return: dict - A dictionary containing the list of files.
+        """
+        logger.debug(f"Retrieving file list for project {project}")
+
+        response = self.api_service.get(
+            endpoint=GET_ALL_FILES_V1,
+            params={
+                "organization": organization,
+                "project": project
+            }
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "retrieve file list for project", project=project)

pygeai/core/files/endpoints.py

@@ -0,0 +1,5 @@
+UPLOAD_FILE_V1 = "v1/files"	# POST -> Uploads a file
+GET_FILE_V1 = "v1/files/{fileId}"	 # GET -> Gets a file by Id
+DELETE_FILE_V1 = "v1/files/{fileId}"	 # DELETE -> Deletes a file by Id
+GET_FILE_CONTENT_V1 = "v1/files/{fileId}/content"  # GET -> Gets the content of a file by Id
+GET_ALL_FILES_V1 = "v1/files/all" 	# GET -> Gets all files