pygeai 0.1.51b3__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/core/common/config.py

@@ -1,9 +1,10 @@
 import os
 import sys
-from functools import lru_cache
 from pathlib import Path
 import configparser
 
+from pygeai import logger
+
 HOME_DIR = Path.home()
 SETTINGS_DIR = HOME_DIR / ".geai"
 SETTINGS_DIR.mkdir(parents=True, exist_ok=True)
@@ -19,9 +20,13 @@ class SettingsManager:
     GEAI_SETTINGS_DIR = str(SETTINGS_DIR)
     GEAI_CREDS_FILE = SETTINGS_DIR / "credentials"
 
-    def __init__(self):
+    def __init__(self, credentials_file: str = None):
         self.config = configparser.ConfigParser()
-
+        
+        if credentials_file:
+            self.GEAI_CREDS_FILE = Path(credentials_file)
+            logger.debug(f"Using custom credentials file: {self.GEAI_CREDS_FILE}")
+        
         if self.GEAI_CREDS_FILE.exists():
             self.config.read(self.GEAI_CREDS_FILE)
         else:
@@ -35,13 +40,18 @@ class SettingsManager:
     def get_setting_value(self, setting_key: str, alias: str):
         """Reads a setting value for a specific alias from the credentials file."""
         if alias not in self.config:
-            raise ValueError(f"Alias '{alias}' not found in the credentials file.")
-
+            logger.warning(f"Alias '{alias}' not found in the credentials file.")
+            return
+        
         if setting_key not in self.config[alias]:
             sys.stdout.write(f"'{setting_key}' not found in alias '{alias}' in the credentials file. Adding empty value.\n")
-            # SET ADDITIONAL URLS
+            # SET ADDITIONAL VARS
             if setting_key.lower() == "GEAI_API_EVAL_URL".lower():
                 self.set_eval_url("", alias)
+            if setting_key.lower() == "GEAI_OAUTH_ACCESS_TOKEN".lower():
+                self.set_access_token("", alias)
+            if setting_key.lower() == "GEAI_PROJECT_ID".lower():
+                self.set_project_id("", alias)
 
         return self.config[alias].get(setting_key, "")
 
@@ -56,7 +66,7 @@ class SettingsManager:
             self.config.write(file)
 
     def get_api_key(self, alias: str = "default"):
-        api_key = os.environ.get("GEAI_API_KEY") if alias == "default" else None
+        api_key = os.environ.get("GEAI_API_KEY") if not alias or alias == "default" else None
         if not api_key:
             api_key = self.get_setting_value("GEAI_API_KEY", alias)
 
@@ -66,7 +76,7 @@ class SettingsManager:
         self.set_setting_value("GEAI_API_KEY", api_key, alias)
 
     def get_base_url(self, alias: str = "default"):
-        base_url = os.environ.get("GEAI_API_BASE_URL") if alias == "default" else None
+        base_url = os.environ.get("GEAI_API_BASE_URL") if not alias or alias == "default" else None
         if not base_url:
             base_url = self.get_setting_value("GEAI_API_BASE_URL", alias)
 
@@ -75,8 +85,28 @@ class SettingsManager:
     def set_base_url(self, base_url, alias: str = "default"):
         self.set_setting_value("GEAI_API_BASE_URL", base_url, alias)
 
+    def get_access_token(self, alias: str = "default"):
+        access_token = os.environ.get("GEAI_OAUTH_ACCESS_TOKEN") if not alias or alias == "default" else None
+        if not access_token:
+            access_token = self.get_setting_value("GEAI_OAUTH_ACCESS_TOKEN", alias)
+
+        return access_token
+
+    def set_access_token(self, access_token, alias: str = "default"):
+        self.set_setting_value("GEAI_OAUTH_ACCESS_TOKEN", access_token, alias)
+
+    def get_project_id(self, alias: str = "default"):
+        project_id = os.environ.get("GEAI_PROJECT_ID") if not alias or alias == "default" else None
+        if not project_id:
+            project_id = self.get_setting_value("GEAI_PROJECT_ID", alias)
+
+        return project_id
+
+    def set_project_id(self, project_id, alias: str = "default"):
+        self.set_setting_value("GEAI_PROJECT_ID", project_id, alias)
+
     def get_eval_url(self, alias: str = "default"):
-        eval_url = os.environ.get("GEAI_API_EVAL_URL") if alias == "default" else None
+        eval_url = os.environ.get("GEAI_API_EVAL_URL") if not alias or alias == "default" else None
         if not eval_url:
             eval_url = self.get_setting_value("GEAI_API_EVAL_URL", alias)
 
@@ -85,17 +115,51 @@ class SettingsManager:
     def set_eval_url(self, eval_url, alias: str = "default"):
         self.set_setting_value("GEAI_API_EVAL_URL", eval_url, alias)
 
+    def list_aliases(self):
+        """Returns a dict of all aliases and their base URLs."""
+        return {
+            section: self.config[section].get("GEAI_API_BASE_URL", "")
+            for section in self.config.sections()
+        }
+
+    def remove_alias(self, alias: str):
+        """Removes a specific alias and its settings from the credentials file."""
+        if alias in self.config:
+            self.config.remove_section(alias)
+            with self.GEAI_CREDS_FILE.open("w") as file:
+                self.config.write(file)
+            logger.info(f"Alias '{alias}' removed from the credentials file.")
+        else:
+            logger.warning(f"Alias '{alias}' not found in the credentials file.")
+
+
+_settings_instance = None
+
+
+def get_settings(credentials_file: str = None):
+    """
+    Get or create the SettingsManager instance.
+    
+    :param credentials_file: Optional path to a custom credentials file.
+                            If provided on first call, uses that file.
+                            Subsequent calls ignore this parameter.
+    :return: SettingsManager instance
+    """
+    global _settings_instance
+    if _settings_instance is None:
+        _settings_instance = SettingsManager(credentials_file=credentials_file)
+    return _settings_instance
+
 
-@lru_cache()
-def get_settings():
-    return SettingsManager()
+def reset_settings():
+    """Reset the settings instance. Useful for testing."""
+    global _settings_instance
+    _settings_instance = None
 
 
 if __name__ == "__main__":
     settings = get_settings()
-    geai_api_key = settings.get_api_key()
     geai_base_url = settings.get_base_url()
     geai_eval_url = settings.get_eval_url()
-    print(f"api_key: {geai_api_key}")
     print(f"base_url: {geai_base_url}")
     print(f"eval_url: {geai_eval_url}")

pygeai/core/common/exceptions.py

@@ -6,29 +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):
-    """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):
+    """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

@@ -1,8 +1,10 @@
-import json
-from typing import Any, Union
 
+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):
@@ -41,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,
@@ -61,6 +77,8 @@ class EmbeddingsClient(BaseClient):
         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"
@@ -70,6 +88,6 @@ class EmbeddingsClient(BaseClient):
             data=data,
             headers=headers
         )
-        result = response.json()
-        return result
-
+        validate_status_code(response)
+        return parse_json_response(response, "generate embeddings")
+        

pygeai/core/embeddings/managers.py

@@ -1,4 +1,6 @@
+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
@@ -8,7 +10,7 @@ from pygeai.core.handlers import ErrorHandler
 
 class EmbeddingsManager:
 
-    def __init__(self, api_key: str = None, base_url: str = None, alias: str = "default"):
+    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(
@@ -38,6 +40,7 @@ class EmbeddingsManager:
             - 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,
@@ -51,7 +54,9 @@ class EmbeddingsManager:
         )
 
         if ErrorHandler.has_errors(response_data):
-            result = ErrorHandler.extract_error(response_data)
-        else:
-            result = EmbeddingsResponseMapper.map_to_embedding_response(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

@@ -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

@@ -1,8 +1,11 @@
-import json
 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):
@@ -35,11 +38,13 @@ class FeedbackClient(BaseClient):
         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
         )
-        result = response.json()
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "send feedback. JSON parsing error")
 

pygeai/core/files/clients.py

@@ -2,9 +2,13 @@ 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):
@@ -43,18 +47,17 @@ class FileClient(BaseClient):
 
         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
             )
-            try:
-                result = response.json()
-            except JSONDecodeError as e:
-                result = response.text
+            validate_status_code(response)
+            return parse_json_response(response, "upload file in project", file_name=file_name, project_id=project_id)
 
-            return result
         finally:
             files["file"].close()
 
@@ -75,13 +78,9 @@ class FileClient(BaseClient):
                 "project": project
             }
         )
-
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        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:
         """
@@ -96,6 +95,9 @@ class FileClient(BaseClient):
         headers = {
             "Accept": "application/json",
         }
+
+        logger.debug(f"Deleting file with id {file_id}")
+
         response = self.api_service.delete(
             endpoint=endpoint,
             headers=headers,
@@ -104,12 +106,8 @@ class FileClient(BaseClient):
                 "project": project
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        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:
         """
@@ -121,6 +119,9 @@ class FileClient(BaseClient):
         :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={
@@ -142,6 +143,8 @@ class FileClient(BaseClient):
         :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={
@@ -149,9 +152,5 @@ class FileClient(BaseClient):
                 "project": project
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "retrieve file list for project", project=project)