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

pygeai/cli/error_handler.py

@@ -0,0 +1,116 @@
+import traceback
+from difflib import SequenceMatcher
+from typing import List, Optional
+
+from pygeai import logger
+from pygeai.cli.commands import Command, Option
+from pygeai.core.utils.console import Console
+
+
+class ExitCode:
+    SUCCESS = 0
+    USER_INPUT_ERROR = 1
+    MISSING_REQUIREMENT = 2
+    SERVICE_ERROR = 3
+    KEYBOARD_INTERRUPT = 130
+    UNEXPECTED_ERROR = 255
+
+
+class ErrorHandler:
+
+    @staticmethod
+    def format_error(error_type: str, message: str, suggestion: Optional[str] = None, show_help: bool = True) -> str:
+        output = f"ERROR: {message}"
+        
+        if suggestion:
+            output += f"\n  → {suggestion}"
+        
+        if show_help:
+            output += "\n\nRun 'geai help' for usage information."
+        
+        return output
+
+    @staticmethod
+    def find_similar_items(item: str, available_items: List[str], threshold: float = 0.6) -> List[str]:
+        similarities = []
+        for available in available_items:
+            ratio = SequenceMatcher(None, item.lower(), available.lower()).ratio()
+            if ratio >= threshold:
+                similarities.append((available, ratio))
+        
+        similarities.sort(key=lambda x: x[1], reverse=True)
+        return [item[0] for item in similarities[:3]]
+
+    @staticmethod
+    def get_available_commands(commands: List[Command]) -> List[str]:
+        all_identifiers = []
+        for cmd in commands:
+            all_identifiers.extend(cmd.identifiers)
+        return all_identifiers
+
+    @staticmethod
+    def get_available_options(options: List[Option]) -> List[str]:
+        all_identifiers = []
+        for opt in options:
+            all_identifiers.extend(opt.identifiers)
+        return all_identifiers
+
+    @staticmethod
+    def handle_unknown_command(command: str, available_commands: List[Command]) -> str:
+        cmd_identifiers = ErrorHandler.get_available_commands(available_commands)
+        similar = ErrorHandler.find_similar_items(command, cmd_identifiers)
+        
+        message = f"'{command}' is not a valid command."
+        
+        if similar:
+            suggestion = f"Did you mean: {', '.join(similar)}?"
+        else:
+            suggestion = f"Available commands: {', '.join(sorted(set([cmd.identifiers[0] for cmd in available_commands])))}"
+        
+        return ErrorHandler.format_error("Unknown Command", message, suggestion)
+
+    @staticmethod
+    def handle_unknown_option(option: str, available_options: List[Option]) -> str:
+        opt_identifiers = ErrorHandler.get_available_options(available_options)
+        similar = ErrorHandler.find_similar_items(option, opt_identifiers)
+        
+        message = f"'{option}' is not a valid option."
+        
+        if similar:
+            suggestion = f"Did you mean: {', '.join(similar)}?"
+        else:
+            suggestion = f"Available options: {', '.join(sorted(set([opt.identifiers[0] for opt in available_options])))}"
+        
+        return ErrorHandler.format_error("Unknown Option", message, suggestion)
+
+    @staticmethod
+    def handle_missing_requirement(requirement_message: str) -> str:
+        message = requirement_message
+        suggestion = "Please provide all required parameters."
+        return ErrorHandler.format_error("Missing Requirement", message, suggestion)
+
+    @staticmethod
+    def handle_invalid_agent(error_message: str) -> str:
+        message = f"Failed to retrieve or validate the agent.\n  Details: {error_message}"
+        suggestion = "Check your agent configuration and ensure the agent exists."
+        return ErrorHandler.format_error("Invalid Agent", message, suggestion)
+
+    @staticmethod
+    def handle_wrong_argument(error_message: str, usage: str) -> str:
+        Console.write_stderr(f"usage: {usage}")
+        message = error_message
+        suggestion = "Check the command syntax and try again."
+        return ErrorHandler.format_error("Invalid Argument", message, suggestion)
+
+    @staticmethod
+    def handle_keyboard_interrupt() -> str:
+        return "\n\nOperation cancelled by user."
+
+    @staticmethod
+    def handle_unexpected_error(exception: Exception) -> str:
+        logger.error(f"Unexpected error occurred: {exception}")
+        logger.error(traceback.format_exc())
+        
+        message = "An unexpected error occurred. This may be a bug."
+        suggestion = f"Please report this issue to geai-sdk@globant.com with the following details:\n  Error: {str(exception)}\n  Run with geai-dbg for more details."
+        return ErrorHandler.format_error("Critical Error", message, suggestion, show_help=False)

pygeai/cli/geai.py

@@ -5,6 +5,7 @@ from pygeai.cli.commands.base import base_commands, base_options
 from pygeai.cli.commands import ArgumentsEnum, Command
 from pygeai.cli.parsers import CommandParser
 from pygeai.cli.texts.help import CLI_USAGE
+from pygeai.cli.error_handler import ErrorHandler, ExitCode
 from pygeai.core.base.session import get_session
 from pygeai.core.common.exceptions import UnknownArgumentError, MissingRequirementException, WrongArgumentError, \
     InvalidAgentException
@@ -64,19 +65,37 @@ class CLIDriver:
                 arguments = []
 
             self.process_command(command, arguments)
-        except (UnknownArgumentError, WrongArgumentError) as e:
-            Console.write_stderr(f"usage: {CLI_USAGE}")
-            Console.write_stderr(str(e))
-            Console.write_stderr()
+            return ExitCode.SUCCESS
+        except UnknownArgumentError as e:
+            if hasattr(e, 'available_commands') and e.available_commands:
+                error_msg = ErrorHandler.handle_unknown_command(e.arg, e.available_commands)
+            elif hasattr(e, 'available_options') and e.available_options:
+                error_msg = ErrorHandler.handle_unknown_option(e.arg, e.available_options)
+            else:
+                error_msg = ErrorHandler.format_error("Unknown Argument", str(e))
+            
+            Console.write_stderr(error_msg)
+            return ExitCode.USER_INPUT_ERROR
+        except WrongArgumentError as e:
+            error_msg = ErrorHandler.handle_wrong_argument(str(e), CLI_USAGE)
+            Console.write_stderr(error_msg)
+            return ExitCode.USER_INPUT_ERROR
         except MissingRequirementException as e:
-            Console.write_stderr(f"ERROR: Something is missing! \nDetail: {e}")
+            error_msg = ErrorHandler.handle_missing_requirement(str(e))
+            Console.write_stderr(error_msg)
+            return ExitCode.MISSING_REQUIREMENT
         except InvalidAgentException as e:
-            Console.write_stderr(f"ERROR: There was an error retrieving the agent. \nDetail: {e}")
+            error_msg = ErrorHandler.handle_invalid_agent(str(e))
+            Console.write_stderr(error_msg)
+            return ExitCode.SERVICE_ERROR
         except KeyboardInterrupt:
-            Console.write_stdout()
+            message = ErrorHandler.handle_keyboard_interrupt()
+            Console.write_stdout(message)
+            return ExitCode.KEYBOARD_INTERRUPT
         except Exception as e:
-            Console.write_stderr(f"CRITICAL: There has ben an unexpected error. Please report this bug to geai-sdk@globant.com. Error: {e}")
-            return 255
+            error_msg = ErrorHandler.handle_unexpected_error(e)
+            Console.write_stderr(error_msg)
+            return ExitCode.UNEXPECTED_ERROR
 
     def process_command(self, command: Command, arguments: list[str]):
         """
@@ -107,4 +126,3 @@ class CLIDriver:
             else:
                 option_list = CommandParser(None, subcommand.options).extract_option_list(subcommand_arguments)
                 subcommand.action(option_list)
-

pygeai/cli/parsers.py

@@ -18,7 +18,10 @@ class CommandParser:
         """
         command = self._get_associated_command(arg)
         if not command:
-            raise UnknownArgumentError(f"'{arg}' is not a valid command. Run with help or h to check usage.")
+            error = UnknownArgumentError(f"'{arg}' is not a valid command.")
+            error.arg = arg
+            error.available_commands = self.available_commands
+            raise error
 
         return command
 
@@ -39,7 +42,10 @@ class CommandParser:
 
             flag = self._get_associated_option(arg)
             if not flag:
-                raise UnknownArgumentError(f"'{arg}' is not a valid option. Run with help or h to check usage.")
+                error = UnknownArgumentError(f"'{arg}' is not a valid option.")
+                error.arg = arg
+                error.available_options = self.available_options
+                raise error
 
             if flag.requires_args:
                 complementary_arg = True

pygeai/core/base/clients.py

@@ -20,7 +20,9 @@ class BaseClient(ABC):
             if not self.__session:
                 raise MissingRequirementException("API KEY and BASE URL must be defined in order to use this functionality")
         elif api_key and base_url:
-            self.__session = Session(api_key=api_key, base_url=base_url)
+            self.__session = get_session()
+            self.__session.api_key = api_key
+            self.__session.base_url = base_url
         else:
             self.__session = get_session()
 

pygeai/core/common/exceptions.py

@@ -6,55 +6,56 @@ class GEAIException(Exception):
 
 
 class UnknownArgumentError(GEAIException):
-    """Argument provided is not valid"""
+    """Raised when an unknown or invalid command/option is provided"""
     pass
 
 
 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 ServerResponseError(GEAIException):
-    """There was an error in the request to the server"""
+    """Raised when the server returns an error response"""
     pass
 
 
 class APIError(GEAIException):
-    """There was an error in the request to the server"""
+    """Raised when an API request fails"""
     pass
 
 
 class InvalidPathException(GEAIException):
-    """There was an error trying to find the file in the specified path"""
+    """Raised when a file or directory path is invalid or not found"""
     pass
 
 
 class InvalidJSONException(GEAIException):
-    """There was an error trying to load data from the JSON file"""
+    """Raised when JSON data cannot be parsed or is malformed"""
     pass
 
 
 class InvalidAPIResponseException(GEAIException):
-    """There was an error handling response from the server"""
+    """Raised when the API response format is unexpected or invalid"""
     pass
 
 
 class InvalidResponseException(GEAIException):
-    """There was an error getting a response from the server"""
+    """Raised when a response cannot be retrieved or processed"""
     pass
 
 
 class InvalidAgentException(GEAIException):
-    """There was an error getting a response from the server"""
+    """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

@@ -1,7 +1,7 @@
 
 from pygeai import logger
 from pygeai.core.base.clients import BaseClient
-from pygeai.core.common.exceptions import InvalidAPIResponseException
+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
@@ -43,7 +43,21 @@ class EmbeddingsClient(BaseClient):
 
         :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,
@@ -74,5 +88,6 @@ class EmbeddingsClient(BaseClient):
             data=data,
             headers=headers
         )
+        validate_status_code(response)
         return parse_json_response(response, "generate embeddings")
-
+        

pygeai/core/embeddings/mappers.py

@@ -1,4 +1,4 @@
-from pygeai.core.embeddings.responses import EmbeddingResponse, EmbeddingData, UsageInfo
+from pygeai.core.embeddings.responses import EmbeddingResponse, EmbeddingData, UsageInfo, TokenDetails
 
 
 class EmbeddingsResponseMapper:
@@ -29,10 +29,24 @@ class EmbeddingsResponseMapper:
 
     @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)
+            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/responses.py

@@ -1,11 +1,16 @@
-from typing import List
+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: List[float]
+    embedding: Union[List[float], str]
     object: str
 
 
@@ -15,6 +20,8 @@ class UsageInfo(BaseModel):
     total_tokens: int
     currency: str
     prompt_cost: float
+    completion_tokens_details: Optional[TokenDetails] = None
+    prompt_tokens_details: Optional[TokenDetails] = None
 
 
 class EmbeddingResponse(BaseModel):

pygeai/core/feedback/clients.py

@@ -45,5 +45,6 @@ class FeedbackClient(BaseClient):
             endpoint=endpoint,
             data=data
         )
+        validate_status_code(response)
         return parse_json_response(response, "send feedback. JSON parsing error")
 

pygeai/core/files/clients.py

@@ -55,13 +55,8 @@ class FileClient(BaseClient):
                 headers=headers,
                 files=files
             )
-            try:
-                result = response.json()
-                return result
-            except JSONDecodeError as e:
-                logger.error(
-                    f"Unable to upload file {file_name} in project {project_id}: JSON parsing error (status {response.status_code}): {e}. Response: {response.text}")
-                raise InvalidAPIResponseException(f"Unable to upload file {file_name}: {response.text}")
+            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()
@@ -84,6 +79,7 @@ class FileClient(BaseClient):
             }
         )
         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:
@@ -110,6 +106,7 @@ class FileClient(BaseClient):
                 "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:
@@ -155,4 +152,5 @@ class FileClient(BaseClient):
                 "project": project
             }
         )
+        validate_status_code(response)
         return parse_json_response(response, "retrieve file list for project", project=project)

pygeai/core/files/managers.py

@@ -1,3 +1,7 @@
+import tempfile
+from pathlib import Path
+from typing import Optional
+
 from pygeai import logger
 from pygeai.admin.clients import AdminClient
 from pygeai.core.base.mappers import ErrorMapper, ResponseMapper
@@ -180,3 +184,41 @@ class FileManager:
 
         result = FileResponseMapper.map_to_file_list_response(response_data)
         return result
+
+    def upload_file_from_content(
+            self,
+            file_name: str,
+            content: bytes,
+            folder: Optional[str] = None
+    ) -> UploadFileResponse:
+        """
+        Uploads a file from binary content to the specified organization and project.
+
+        This method creates a temporary file from the provided content, uploads it,
+        and then cleans up the temporary file.
+
+        :param file_name: str - The name for the uploaded file.
+        :param content: bytes - The binary content of the file.
+        :param folder: str, optional - Destination folder (default is None, which means temporary storage).
+        :return: UploadFileResponse - The response object containing the uploaded file details.
+        :raises APIError: If the API returns errors.
+        """
+        temp_file = None
+        try:
+            suffix = Path(file_name).suffix or ""
+            with tempfile.NamedTemporaryFile(mode='wb', suffix=suffix, delete=False) as temp_file:
+                temp_file.write(content)
+                temp_file_path = temp_file.name
+
+            upload_file = UploadFile(
+                path=temp_file_path,
+                name=file_name,
+                folder=folder
+            )
+            return self.upload_file(upload_file)
+        finally:
+            if temp_file:
+                try:
+                    Path(temp_file_path).unlink(missing_ok=True)
+                except Exception as e:
+                    logger.warning(f"Failed to delete temporary file {temp_file_path}: {e}")

pygeai/core/llm/clients.py

@@ -13,6 +13,7 @@ class LlmClient(BaseClient):
     def get_provider_list(self) -> dict:
         logger.debug("Obtaining provider list")
         response = self.api_service.get(endpoint=GET_PROVIDER_LIST_V2)
+        validate_status_code(response)
         return parse_json_response(response, "obtain provider list")
 
     def get_provider_data(self, provider_name: str) -> dict:
@@ -21,6 +22,7 @@ class LlmClient(BaseClient):
         logger.debug(f"Obtaining provider data for {provider_name}")
 
         response = self.api_service.get(endpoint=endpoint)
+        validate_status_code(response)
         return parse_json_response(response, "obtain provider data", provider_name=provider_name)
 
     def get_provider_models(self, provider_name: str) -> dict:
@@ -29,6 +31,7 @@ class LlmClient(BaseClient):
         logger.debug(f"Obtaining provider models for {provider_name}")
 
         response = self.api_service.get(endpoint=endpoint)
+        validate_status_code(response)
         return parse_json_response(response, "obtain provider models", provider_name=provider_name)
 
     def get_model_data(
@@ -46,4 +49,5 @@ class LlmClient(BaseClient):
 
         response = self.api_service.get(endpoint=endpoint)
         model_identifier = model_name or model_id
+        validate_status_code(response)
         return parse_json_response(response, f"obtain model data for {provider_name}/{model_identifier}")

pygeai/core/plugins/clients.py

@@ -27,5 +27,6 @@ class PluginClient(BaseClient):
             endpoint=LIST_ASSISTANTS_PLUGINS_V1,
             params=params
         )
+        validate_status_code(response)
         return parse_json_response(response, f"list assistants for organization {organization_id} and project {project_id}")
 

pygeai/core/rerank/clients.py

@@ -30,5 +30,6 @@ class RerankClient(BaseClient):
             endpoint=RERANK_V1,
             data=data
         )
+        validate_status_code(response)
         return parse_json_response(response, "rerank chunks for query with model", query=query, model=model)
 

pygeai/core/secrets/clients.py

@@ -45,6 +45,7 @@ class SecretClient(BaseClient):
             endpoint=LIST_SECRETS_V1,
             params=params
         )
+        validate_status_code(response)
         return parse_json_response(response, "list secrets with params")
 
     def get_secret(self, secret_id: str) -> dict:
@@ -65,6 +66,7 @@ class SecretClient(BaseClient):
         response = self.api_service.get(
             endpoint=endpoint
         )
+        validate_status_code(response)
         return parse_json_response(response, "get secret with ID", secret_id=secret_id)
 
     def create_secret(
@@ -102,6 +104,7 @@ class SecretClient(BaseClient):
             endpoint=CREATE_SECRET_V1,
             data=data
         )
+        validate_status_code(response)
         return parse_json_response(response, "create secret with name", name=name)
 
     def update_secret(
@@ -143,6 +146,7 @@ class SecretClient(BaseClient):
             endpoint=endpoint,
             data=data
         )
+        validate_status_code(response)
         return parse_json_response(response, "update secret with ID", secret_id=secret_id)
 
     def set_secret_accesses(
@@ -183,6 +187,7 @@ class SecretClient(BaseClient):
             endpoint=endpoint,
             data=data
         )
+        validate_status_code(response)
         return parse_json_response(response, "set accesses for secret with ID", secret_id=secret_id)
 
     def get_secret_accesses(self, secret_id: str) -> dict:
@@ -203,4 +208,5 @@ class SecretClient(BaseClient):
         response = self.api_service.get(
             endpoint=endpoint
         )
+        validate_status_code(response)
         return parse_json_response(response, "get accesses for secret with ID", secret_id=secret_id)

pygeai/core/services/rest.py

@@ -388,7 +388,7 @@ class ApiService:
 
     def _add_endpoint_to_url(self, endpoint: str):
         clean_base_url = self.base_url.rstrip('/')
-        url = f"{clean_base_url}/{endpoint}" if self._has_valid_protocol(clean_base_url) else f"https://{clean_base_url}/{endpoint}"
+        url = f"{clean_base_url}/{endpoint.lstrip('/')}" if self._has_valid_protocol(clean_base_url) else f"https://{clean_base_url}/{endpoint}"
         return url
 
     def _has_valid_protocol(self, url: str):

pygeai/dbg/__init__.py

@@ -0,0 +1,3 @@
+from pygeai.dbg.debugger import Debugger, Breakpoint
+
+__all__ = ['Debugger', 'Breakpoint']