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

pygeai/cli/error_handler.py

@@ -1,12 +1,16 @@
 import traceback
 from difflib import SequenceMatcher
-from typing import List, Optional
+from typing import List, Optional, Tuple
 
 from pygeai import logger
 from pygeai.cli.commands import Command, Option
 from pygeai.core.utils.console import Console
 
 
+FUZZY_MATCH_THRESHOLD = 0.6
+MAX_FUZZY_SUGGESTIONS = 3
+
+
 class ExitCode:
     SUCCESS = 0
     USER_INPUT_ERROR = 1
@@ -19,27 +23,58 @@ class ExitCode:
 class ErrorHandler:
 
     @staticmethod
-    def format_error(error_type: str, message: str, suggestion: Optional[str] = None, show_help: bool = True) -> str:
-        output = f"ERROR: {message}"
+    def format_error(
+        error_type: str, 
+        message: str, 
+        suggestion: Optional[str] = None, 
+        show_help: bool = True,
+        example: Optional[str] = None
+    ) -> str:
+        """
+        Formats an error message with optional suggestion and example.
+
+        :param error_type: str - Type of error (e.g., "Unknown Command").
+        :param message: str - The error message.
+        :param suggestion: Optional[str] - Suggested fix or next steps.
+        :param show_help: bool - Whether to show help command hint.
+        :param example: Optional[str] - Example of correct usage.
+        :return: str - Formatted error message.
+        """
+        output = f"ERROR [{error_type}]: {message}"
         
         if suggestion:
             output += f"\n  → {suggestion}"
         
+        if example:
+            output += f"\n\n  Example:\n    {example}"
+        
         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 = []
+    def find_similar_items(
+        item: str, 
+        available_items: List[str], 
+        threshold: float = FUZZY_MATCH_THRESHOLD
+    ) -> List[str]:
+        """
+        Finds similar items using fuzzy string matching.
+
+        :param item: str - The item to match against.
+        :param available_items: List[str] - List of available items.
+        :param threshold: float - Minimum similarity ratio (0.0 to 1.0).
+        :return: List[str] - List of similar items, up to MAX_FUZZY_SUGGESTIONS.
+        """
+        similarities: List[Tuple[str, float]] = []
         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]]
+        return [item[0] for item in similarities[:MAX_FUZZY_SUGGESTIONS]]
 
     @staticmethod
     def get_available_commands(commands: List[Command]) -> List[str]:

pygeai/cli/geai.py

@@ -1,4 +1,6 @@
 import sys
+import logging
+from typing import List, Optional
 
 from pygeai import logger
 from pygeai.cli.commands.base import base_commands, base_options
@@ -12,18 +14,61 @@ from pygeai.core.common.exceptions import UnknownArgumentError, MissingRequireme
 from pygeai.core.utils.console import Console
 
 
-def main():
+def setup_verbose_logging() -> None:
+    """
+    Configure verbose logging for the CLI.
+    
+    Sets up a console handler with DEBUG level logging and a formatted output
+    that includes timestamp, logger name, level, and message.
+    """
+    if logger.handlers:
+        for handler in logger.handlers:
+            if not isinstance(handler, logging.NullHandler):
+                return
+    
+    logger.setLevel(logging.DEBUG)
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(logging.DEBUG)
+    formatter = logging.Formatter(
+        '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+    logger.propagate = False
+    logger.debug("Verbose mode enabled")
+
+
+def main() -> int:
+    """
+    Main entry point for the GEAI CLI application.
+
+    :return: int - Exit code indicating success or error.
+    """
     driver = CLIDriver()
     return driver.main()
 
 
 class CLIDriver:
-
-    def __init__(self, session=None):
+    """
+    Main CLI driver for the GEAI command-line interface.
+    
+    The CLIDriver orchestrates command parsing, execution, and error handling
+    for all GEAI CLI operations. It supports multi-profile session management
+    via the --alias flag and provides comprehensive error handling with
+    user-friendly messages.
+    """
+
+    def __init__(self, session=None) -> None:
         """
-        Sets session to be used while running the command, either with a specified alias,
-        environment variables or function parameters.
-        Once the session is defined, it won't change during the curse of the execution.
+        Initialize the CLI driver with optional session.
+        
+        Sets up the session to be used while running commands, either with a 
+        specified alias, environment variables, or function parameters.
+        Once the session is defined, it won't change during the execution.
+        
+        :param session: Optional session object. If None, uses 'default' or
+                       alias-specified session from command-line arguments.
         """
         arguments = sys.argv
         if "-a" in arguments or "--alias" in arguments:
@@ -32,9 +77,13 @@ class CLIDriver:
 
         self.session = get_session("default") if session is None else session
 
-    def _get_alias(self, arguments: list):
+    def _get_alias(self, arguments: List[str]) -> str:
         """
-        Retrieves and removes alias and alias flag from argument list
+        Retrieves and removes alias and alias flag from argument list.
+
+        :param arguments: List[str] - Command line arguments.
+        :return: str - The alias value.
+        :raises ValueError: If alias flag is present but no value provided.
         """
         alias_index = None
 
@@ -47,24 +96,46 @@ class CLIDriver:
         alias = arguments.pop(alias_index)
         return alias
 
-    def main(self, args=None):
+    def main(self, args: Optional[List[str]] = None) -> int:
         """
-        If not argument is received, it defaults to help (first command in base_command list).
+        Execute the CLI command based on provided arguments.
+        
+        If no argument is received, it defaults to help (first command in base_command list).
         Otherwise, it parses the arguments received to identify the appropriate command and either
         execute it or parse it again to detect subcommands.
+
+        :param args: Optional[List[str]] - Command line arguments. If None, uses sys.argv.
+        :return: int - Exit code (0 for success, non-zero for errors).
         """
         try:
-            logger.debug(f"Running geai with: {' '.join(a for a in sys.argv)}")
-            if len(sys.argv) > 1:
-                arg = sys.argv[1] if args is None else args[1]
-                arguments = sys.argv[2:] if args is None else args[2:]
-
+            argv = sys.argv if args is None else args
+            
+            if "--verbose" in argv or "-v" in argv:
+                setup_verbose_logging()
+                argv_copy = [a for a in argv if a not in ("--verbose", "-v")]
+                if args is None:
+                    sys.argv = argv_copy
+                else:
+                    args = argv_copy
+                argv = argv_copy
+            
+            logger.debug(f"Running geai with: {' '.join(a for a in argv)}")
+            logger.debug(f"Session: {self.session.alias if hasattr(self.session, 'alias') else 'default'}")
+            
+            if len(argv) > 1:
+                arg = argv[1] if args is None else args[1]
+                arguments = argv[2:] if args is None else args[2:]
+                
+                logger.debug(f"Identifying command for argument: {arg}")
                 command = CommandParser(base_commands, base_options).identify_command(arg)
+                logger.debug(f"Command identified: {command.name}")
             else:
+                logger.debug("No arguments provided, defaulting to help command")
                 command = base_commands[0]
                 arguments = []
 
             self.process_command(command, arguments)
+            logger.debug(f"Command completed successfully")
             return ExitCode.SUCCESS
         except UnknownArgumentError as e:
             if hasattr(e, 'available_commands') and e.available_commands:
@@ -102,27 +173,39 @@ class CLIDriver:
         If the command has no action associated with it, it means it has subcommands, so it must be parsed again
         to identify it.
         """
+        logger.debug(f"Processing command: {command.name}, arguments: {arguments}")
+        
         if command.action:
             if command.additional_args == ArgumentsEnum.NOT_AVAILABLE:
+                logger.debug(f"Executing command {command.name} without arguments")
                 command.action()
             else:
+                logger.debug(f"Extracting options for command {command.name}")
                 option_list = CommandParser(base_commands, command.options).extract_option_list(arguments)
+                logger.debug(f"Options extracted: {len(option_list)} items")
                 command.action(option_list)
         elif command.subcommands:
             subcommand_arg = arguments[0] if len(arguments) > 0 else None
             subcommand_arguments = arguments[1:] if len(arguments) > 1 else []
-
+            
+            logger.debug(f"Command has subcommands, identifying: {subcommand_arg}")
+            
             available_commands = command.subcommands
             available_options = command.options
             parser = CommandParser(available_commands, available_options)
 
             if not subcommand_arg:
+                logger.debug(f"No subcommand specified, using default: {command.subcommands[0].name}")
                 subcommand = command.subcommands[0]
             else:
                 subcommand = parser.identify_command(subcommand_arg)
+                logger.debug(f"Subcommand identified: {subcommand.name}")
 
             if subcommand.additional_args == ArgumentsEnum.NOT_AVAILABLE:
+                logger.debug(f"Executing subcommand {subcommand.name} without arguments")
                 subcommand.action()
             else:
+                logger.debug(f"Extracting options for subcommand {subcommand.name}")
                 option_list = CommandParser(None, subcommand.options).extract_option_list(subcommand_arguments)
+                logger.debug(f"Options extracted: {len(option_list)} items")
                 subcommand.action(option_list)

pygeai/cli/parsers.py

@@ -1,3 +1,6 @@
+from typing import List, Tuple, Optional
+
+from pygeai import logger
 from pygeai.cli.commands.base import base_options
 from pygeai.cli.commands import Command, Option
 from pygeai.core.common.exceptions import UnknownArgumentError, MissingRequirementException
@@ -5,7 +8,17 @@ from pygeai.core.common.exceptions import UnknownArgumentError, MissingRequireme
 
 class CommandParser:
 
-    def __init__(self, available_commands, available_options):
+    def __init__(
+        self, 
+        available_commands: Optional[List[Command]], 
+        available_options: Optional[List[Option]]
+    ) -> None:
+        """
+        Initialize a CommandParser with available commands and options.
+
+        :param available_commands: Optional[List[Command]] - List of valid commands, or None.
+        :param available_options: Optional[List[Option]] - List of valid options, or None.
+        """
         self.available_commands = available_commands
         self.available_options = available_options
 
@@ -13,26 +26,34 @@ class CommandParser:
         """
         Analyzes the first argument and checks if it's a valid command.
 
-        :param first_argument: The first argument to be analyzed.
-        :return: The command to be run.
+        :param arg: str - The argument to be analyzed.
+        :return: Command - The identified command object.
+        :raises UnknownArgumentError: If the argument is not a valid command.
         """
+        logger.debug(f"Searching for command matching: {arg}")
         command = self._get_associated_command(arg)
         if not command:
-            error = UnknownArgumentError(f"'{arg}' is not a valid command.")
-            error.arg = arg
-            error.available_commands = self.available_commands
-            raise error
-
+            logger.debug(f"No command found for: {arg}")
+            raise UnknownArgumentError(
+                f"'{arg}' is not a valid command.",
+                arg=arg,
+                available_commands=self.available_commands
+            )
+        
+        logger.debug(f"Command found: {command.name} (identifiers: {command.identifiers})")
         return command
 
-    def extract_option_list(self, arguments: list) -> list[(Option, str)]:
+    def extract_option_list(self, arguments: List[str]) -> List[Tuple[Option, str]]:
         """
-        Parses a list of arguments and returns the commands being invoked.
+        Parses a list of arguments and returns the options being invoked.
 
-        :param arguments: list - The list of arguments received by the CLI utility.
-        :return: list - A list of flags and their associated arguments.
+        :param arguments: List[str] - The list of arguments received by the CLI utility.
+        :return: List[Tuple[Option, str]] - A list of tuples containing Option objects and their values.
+        :raises UnknownArgumentError: If an unknown option is provided.
+        :raises MissingRequirementException: If a required option argument is missing.
         """
-        flag_list = []
+        logger.debug(f"Extracting options from arguments: {arguments}")
+        flag_list: List[Tuple[Option, str]] = []
 
         complementary_arg = False
         for i, arg in enumerate(arguments):
@@ -42,36 +63,59 @@ class CommandParser:
 
             flag = self._get_associated_option(arg)
             if not flag:
-                error = UnknownArgumentError(f"'{arg}' is not a valid option.")
-                error.arg = arg
-                error.available_options = self.available_options
-                raise error
+                logger.debug(f"Unknown option: {arg}")
+                raise UnknownArgumentError(
+                    f"'{arg}' is not a valid option.",
+                    arg=arg,
+                    available_options=self.available_options
+                )
+            
+            logger.debug(f"Option found: {flag.name} (identifiers: {flag.identifiers})")
 
             if flag.requires_args:
                 complementary_arg = True
                 try:
-                    flag_list.append((flag, arguments[i + 1]))
-                except IndexError as e:
+                    value = arguments[i + 1]
+                    logger.debug(f"Option {flag.name} has value: {value}")
+                    flag_list.append((flag, value))
+                except IndexError:
+                    logger.debug(f"Missing required argument for option: {flag.name}")
                     raise MissingRequirementException(f"'{flag.name}' requires an argument.")
             else:
-                flag_list.append([flag, []])
+                logger.debug(f"Option {flag.name} is a flag (no value required)")
+                flag_list.append((flag, ""))
 
+        logger.debug(f"Total options parsed: {len(flag_list)}")
         return flag_list
 
-    def _get_associated_command(self, arg: str) -> Command:
-        associated_command = None
+    def _get_associated_command(self, arg: str) -> Optional[Command]:
+        """
+        Finds the command associated with the given argument.
+
+        :param arg: str - The argument to search for.
+        :return: Optional[Command] - The associated command if found, None otherwise.
+        """
+        if not self.available_commands:
+            return None
+            
         for command in self.available_commands:
             if arg in command.identifiers:
-                associated_command = command
-                break
+                return command
+        
+        return None
 
-        return associated_command
+    def _get_associated_option(self, arg: str) -> Optional[Option]:
+        """
+        Finds the option associated with the given argument.
 
-    def _get_associated_option(self, arg: str) -> Option:
-        associated_option = None
+        :param arg: str - The argument to search for.
+        :return: Optional[Option] - The associated option if found, None otherwise.
+        """
+        if not self.available_options:
+            return None
+            
         for option in self.available_options:
             if arg in option.identifiers:
-                associated_option = option
-                break
-
-        return associated_option
+                return option
+        
+        return None

pygeai/cli/texts/help.py

@@ -340,12 +340,30 @@ DESCRIPTION
 EXAMPLES
     The command:
         
-        geai migrate agent --agent-id "UUID" --target-project "TARGET_UUID"
-    migrates an agent to a different project.
-    
-    The command:
-        geai migrate process --process-id "UUID" --target-project "TARGET_UUID"
-    migrates an agentic process to another project
+        geai migrate clone-project \\
+            --from-api-key "source_api_key_123abc456def789ghi012jkl345mno678pqr901stu234" \\
+            --from-organization-api-key "org_key_abc123def456ghi789jkl012mno345pqr678" \\
+            --from-project-id "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" \\
+            --from-instance "https://api.example.ai" \\
+            --to-project-name "Migrated Project - Complete Clone" \\
+            --admin-email "admin@example.com" \\
+            --all
+    
+    will clone entire project within the same instance
+    
+    The command: 
+    
+        geai migrate clone-project \\
+            --from-api-key "source_api_key_123abc456def789ghi012jkl345mno678pqr901stu234" \\
+            --from-organization-api-key "source_org_key_abc123def456ghi789jkl012mno345pqr678" \\
+            --from-project-id "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" \\
+            --from-instance "https://api.test.example.ai" \\
+            --to-organization-api-key "dest_org_key_stu901vwx234yz567abc890def123ghi456jkl789" \\
+            --to-project-name "Migrated Project - Complete Clone" \\
+            --admin-email "admin@example.com" \\
+            --all
+    
+    will clone entire project with ALL resources (cross-instance)
     
 {AUTHORS_SECTION}
 """
@@ -782,3 +800,54 @@ EXAMPLES
     
 {AUTHORS_SECTION}
 """
+
+ANALYTICS_HELP_TEXT = f"""
+GEAI CLI - ANALYTICS
+--------------------
+
+NAME
+    geai - Command Line Interface for Globant Enterprise AI
+
+SYNOPSIS
+    geai analytics <subcommand> --[flag] [flag_arg]
+
+DESCRIPTION
+    geai analytics is a command from geai cli utility, developed to retrieve analytics and metrics from GEAI.
+    
+    Date Range Defaults:
+    If --start-date and --end-date are not specified, the commands will default to the previous month
+    (from the first day to the last day of the previous month).
+    
+    The options are as follows:
+    {{available_commands}}
+    
+EXAMPLES
+    The command:
+        
+        geai analytics agents-created --start-date "2024-01-01" --end-date "2024-01-31"
+    retrieves the total number of agents created and modified in January 2024.
+    
+    The command:
+        
+        geai analytics full-report
+    retrieves a comprehensive analytics report for the previous month.
+    
+    The command:
+        
+        geai analytics full-report --start-date "2024-01-01" --end-date "2024-01-31" --csv report.csv
+    retrieves a comprehensive analytics report for January 2024 and exports it to report.csv.
+    
+    The command:
+        geai analytics total-cost -s "2024-01-01" -e "2024-01-31"
+    retrieves the total cost for January 2024.
+    
+    The command:
+        geai analytics requests-per-day -s "2024-01-01" -e "2024-01-31"
+    retrieves the total requests per day for January 2024.
+    
+    The command:
+        geai analytics top-agents -s "2024-01-01" -e "2024-01-31"
+    retrieves the top 10 agents by number of requests
+    
+{AUTHORS_SECTION}
+"""

pygeai/core/base/clients.py

@@ -8,20 +8,29 @@ from pygeai.core.utils.validators import validate_status_code
 
 class BaseClient(ABC):
 
-    def __init__(self, api_key: str = None, base_url: str = None, alias: str = None):
+    def __init__(self, api_key: str = None, base_url: str = None, alias: str = None, *,
+                 access_token: str = None, project_id: str = None):
         """
         If commont settings are not specified, they're retrieved from default Session, based on the
         credential files.
         :param api_key: GEAI API KEY to access services
         :param base_url: URL for GEAI instance to be used
+        :param alias: Alias to use from credentials file
+        :param access_token: OAuth access token (keyword-only)
+        :param project_id: Project ID for OAuth authentication (keyword-only)
         """
-        if not (api_key and base_url) and alias:
+        if access_token and not project_id:
+            raise MissingRequirementException("project_id is required when using access_token")
+
+        if not (api_key and base_url) and not (access_token and base_url) and alias:
             self.__session = get_session(alias)
             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:
+        elif (api_key or access_token) and base_url:
             self.__session = get_session()
             self.__session.api_key = api_key
+            self.__session.access_token = access_token
+            self.__session.project_id = project_id
             self.__session.base_url = base_url
         else:
             self.__session = get_session()
@@ -29,7 +38,12 @@ class BaseClient(ABC):
         if self.session is None:
             raise MissingRequirementException("Cannot access this functionality without setting API_KEY and BASE_URL")
 
-        self.__api_service = ApiService(base_url=self.session.base_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.base_url,
+            token=token,
+            project_id=self.session.project_id
+        )
 
     @property
     def session(self):

pygeai/core/base/session.py

@@ -19,6 +19,8 @@ class Session(metaclass=Singleton):
     :param api_key: str - API key to interact with GEAI
     :param base_url: str - Base URL of the GEAI instance
     :param eval_url: Optional[str] - Optional evaluation endpoint URL
+    :param access_token: Optional[str] - OAuth access token (keyword-only)
+    :param project_id: Optional[str] - Project ID for OAuth authentication (keyword-only)
     :return: Session - Instance of the Session class
     :raises: ValueError - If required parameters are missing or invalid
     """
@@ -28,13 +30,22 @@ class Session(metaclass=Singleton):
             api_key: str = None,
             base_url: str = None,
             eval_url: Optional[str] = None,
+            *,
+            access_token: Optional[str] = None,
+            project_id: Optional[str] = None,
+            alias: Optional[str] = None,
     ):
-        if not api_key or not base_url:
-            logger.warning("Cannot instantiate session without api_key and base_url")
+        if not api_key and not access_token:
+            logger.warning("Cannot instantiate session without api_key or access_token")
+        if not base_url:
+            logger.warning("Cannot instantiate session without base_url")
 
         self.__api_key = api_key
         self.__base_url = base_url
         self.__eval_url = eval_url
+        self.__access_token = access_token
+        self.__project_id = project_id
+        self.__alias = alias if alias else "default"
 
         global _session
         _session = self
@@ -63,6 +74,30 @@ class Session(metaclass=Singleton):
     def eval_url(self, eval_url: str):
         self.__eval_url = eval_url
 
+    @property
+    def access_token(self):
+        return self.__access_token
+
+    @access_token.setter
+    def access_token(self, access_token: str):
+        self.__access_token = access_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
+
+    @property
+    def alias(self):
+        return self.__alias
+
+    @alias.setter
+    def alias(self, alias: str):
+        self.__alias = alias
+
 
 def get_session(alias: str = None) -> Session:
     """
@@ -80,13 +115,17 @@ def get_session(alias: str = None) -> Session:
                 api_key=settings.get_api_key(alias),
                 base_url=settings.get_base_url(alias),
                 eval_url=settings.get_eval_url(alias),
+                access_token=settings.get_access_token(alias),
+                project_id=settings.get_project_id(alias),
+                alias=alias,
             )
         elif _session is not None and alias:
-            new_api_key = settings.get_api_key(alias)
-            if new_api_key != _session.api_key:
-                _session.api_key = new_api_key
-                _session.base_url = settings.get_base_url(alias)
-                _session.eval_url = settings.get_eval_url(alias)
+            _session.alias = alias
+            _session.api_key = settings.get_api_key(alias)
+            _session.base_url = settings.get_base_url(alias)
+            _session.eval_url = settings.get_eval_url(alias)
+            _session.access_token = settings.get_access_token(alias)
+            _session.project_id = settings.get_project_id(alias)
 
         if alias:
             logger.debug(f"Alias: {alias}")