pygeai-orchestration 0.1.0b2__py3-none-any.whl

pygeai_orchestration/cli/formatters.py

@@ -0,0 +1,419 @@
+"""CLI output formatters and styling utilities."""
+
+import sys
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class Color(str, Enum):
+    """ANSI color codes."""
+
+    RESET = "\033[0m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    UNDERLINE = "\033[4m"
+
+    BLACK = "\033[30m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    WHITE = "\033[37m"
+
+    BRIGHT_BLACK = "\033[90m"
+    BRIGHT_RED = "\033[91m"
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_MAGENTA = "\033[95m"
+    BRIGHT_CYAN = "\033[96m"
+    BRIGHT_WHITE = "\033[97m"
+
+
+class Symbol(str, Enum):
+    """Unicode symbols for output."""
+
+    SUCCESS = "✓"
+    ERROR = "✗"
+    WARNING = "⚠"
+    INFO = "ℹ"
+    ARROW = "→"
+    BULLET = "•"
+    SPINNER = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+
+class OutputFormatter:
+    """Format CLI output with colors and styling."""
+
+    def __init__(self, use_color: bool = True):
+        """Initialize formatter.
+
+        Args:
+            use_color: Enable color output
+        """
+        self.use_color = use_color and sys.stdout.isatty()
+
+    def colorize(self, text: str, color: Color, bold: bool = False) -> str:
+        """Apply color to text.
+
+        Args:
+            text: Text to colorize
+            color: Color to apply
+            bold: Make text bold
+
+        Returns:
+            Colorized text
+        """
+        if not self.use_color:
+            return text
+
+        result = f"{color}{text}{Color.RESET}"
+        if bold:
+            result = f"{Color.BOLD}{result}"
+        return result
+
+    def success(self, message: str) -> str:
+        """Format success message.
+
+        Args:
+            message: Message text
+
+        Returns:
+            Formatted message
+        """
+        symbol = self.colorize(Symbol.SUCCESS.value, Color.GREEN, bold=True)
+        return f"{symbol} {message}"
+
+    def error(self, message: str) -> str:
+        """Format error message.
+
+        Args:
+            message: Message text
+
+        Returns:
+            Formatted message
+        """
+        symbol = self.colorize(Symbol.ERROR.value, Color.RED, bold=True)
+        return f"{symbol} {message}"
+
+    def warning(self, message: str) -> str:
+        """Format warning message.
+
+        Args:
+            message: Message text
+
+        Returns:
+            Formatted message
+        """
+        symbol = self.colorize(Symbol.WARNING.value, Color.YELLOW, bold=True)
+        return f"{symbol} {message}"
+
+    def info(self, message: str) -> str:
+        """Format info message.
+
+        Args:
+            message: Message text
+
+        Returns:
+            Formatted message
+        """
+        symbol = self.colorize(Symbol.INFO.value, Color.BLUE, bold=True)
+        return f"{symbol} {message}"
+
+    def heading(self, text: str, level: int = 1) -> str:
+        """Format heading.
+
+        Args:
+            text: Heading text
+            level: Heading level (1-3)
+
+        Returns:
+            Formatted heading
+        """
+        if level == 1:
+            return self.colorize(text, Color.CYAN, bold=True)
+        elif level == 2:
+            return self.colorize(text, Color.BLUE, bold=True)
+        else:
+            return self.colorize(text, Color.WHITE, bold=True)
+
+    def dim(self, text: str) -> str:
+        """Format dim text.
+
+        Args:
+            text: Text to dim
+
+        Returns:
+            Formatted text
+        """
+        if not self.use_color:
+            return text
+        return f"{Color.DIM}{text}{Color.RESET}"
+
+    def bold(self, text: str) -> str:
+        """Format bold text.
+
+        Args:
+            text: Text to make bold
+
+        Returns:
+            Formatted text
+        """
+        if not self.use_color:
+            return text
+        return f"{Color.BOLD}{text}{Color.RESET}"
+
+    def key_value(self, key: str, value: Any, indent: int = 0) -> str:
+        """Format key-value pair.
+
+        Args:
+            key: Key text
+            value: Value
+            indent: Indentation level
+
+        Returns:
+            Formatted pair
+        """
+        spaces = "  " * indent
+        key_formatted = self.colorize(key, Color.CYAN)
+        return f"{spaces}{key_formatted}: {value}"
+
+    def bullet_list(self, items: List[str], indent: int = 0) -> str:
+        """Format bullet list.
+
+        Args:
+            items: List items
+            indent: Indentation level
+
+        Returns:
+            Formatted list
+        """
+        spaces = "  " * indent
+        bullet = self.colorize(Symbol.BULLET.value, Color.BLUE)
+        lines = [f"{spaces}{bullet} {item}" for item in items]
+        return "\n".join(lines)
+
+    def section(self, title: str, content: str) -> str:
+        """Format section with title.
+
+        Args:
+            title: Section title
+            content: Section content
+
+        Returns:
+            Formatted section
+        """
+        separator = self.dim("─" * 50)
+        title_formatted = self.heading(title, level=2)
+        return f"\n{title_formatted}\n{separator}\n{content}\n"
+
+    def table(self, headers: List[str], rows: List[List[str]]) -> str:
+        """Format simple table.
+
+        Args:
+            headers: Table headers
+            rows: Table rows
+
+        Returns:
+            Formatted table
+        """
+        if not rows:
+            return ""
+
+        col_widths = [len(h) for h in headers]
+        for row in rows:
+            for i, cell in enumerate(row):
+                col_widths[i] = max(col_widths[i], len(str(cell)))
+
+        header_line = "  ".join(
+            self.bold(h.ljust(w)) for h, w in zip(headers, col_widths)
+        )
+        separator = self.dim("─" * (sum(col_widths) + 2 * (len(headers) - 1)))
+
+        row_lines = []
+        for row in rows:
+            row_line = "  ".join(
+                str(cell).ljust(w) for cell, w in zip(row, col_widths)
+            )
+            row_lines.append(row_line)
+
+        return f"{header_line}\n{separator}\n" + "\n".join(row_lines)
+
+    def json_tree(self, data: Dict[str, Any], indent: int = 0) -> str:
+        """Format JSON-like tree structure.
+
+        Args:
+            data: Dictionary data
+            indent: Current indentation level
+
+        Returns:
+            Formatted tree
+        """
+        lines = []
+        spaces = "  " * indent
+
+        for key, value in data.items():
+            key_formatted = self.colorize(key, Color.CYAN)
+
+            if isinstance(value, dict):
+                lines.append(f"{spaces}{key_formatted}:")
+                lines.append(self.json_tree(value, indent + 1))
+            elif isinstance(value, list):
+                lines.append(f"{spaces}{key_formatted}:")
+                for item in value:
+                    if isinstance(item, dict):
+                        lines.append(self.json_tree(item, indent + 1))
+                    else:
+                        lines.append(f"{spaces}  {Symbol.BULLET.value} {item}")
+            else:
+                value_str = self.colorize(str(value), Color.GREEN)
+                lines.append(f"{spaces}{key_formatted}: {value_str}")
+
+        return "\n".join(lines)
+
+
+class ProgressBar:
+    """Simple progress bar for CLI."""
+
+    def __init__(
+        self,
+        total: int,
+        width: int = 40,
+        formatter: Optional[OutputFormatter] = None
+    ):
+        """Initialize progress bar.
+
+        Args:
+            total: Total number of items
+            width: Width of progress bar
+            formatter: Output formatter
+        """
+        self.total = total
+        self.width = width
+        self.current = 0
+        self.formatter = formatter or OutputFormatter()
+
+    def update(self, n: int = 1) -> None:
+        """Update progress.
+
+        Args:
+            n: Number of items completed
+        """
+        self.current += n
+        self._render()
+
+    def _render(self) -> None:
+        """Render progress bar."""
+        if not sys.stdout.isatty():
+            return
+
+        percent = self.current / self.total if self.total > 0 else 0
+        filled = int(self.width * percent)
+        bar = "█" * filled + "░" * (self.width - filled)
+
+        bar_colored = self.formatter.colorize(bar, Color.GREEN)
+        percent_str = f"{percent * 100:.0f}%"
+
+        line = f"\r[{bar_colored}] {percent_str} ({self.current}/{self.total})"
+        sys.stdout.write(line)
+        sys.stdout.flush()
+
+        if self.current >= self.total:
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+    def finish(self) -> None:
+        """Complete progress bar."""
+        self.current = self.total
+        self._render()
+
+
+class Spinner:
+    """Animated spinner for CLI."""
+
+    def __init__(self, message: str = "", formatter: Optional[OutputFormatter] = None):
+        """Initialize spinner.
+
+        Args:
+            message: Message to display
+            formatter: Output formatter
+        """
+        self.message = message
+        self.formatter = formatter or OutputFormatter()
+        self.frames = list(Symbol.SPINNER)
+        self.current_frame = 0
+        self.running = False
+
+    def start(self) -> None:
+        """Start spinner."""
+        self.running = True
+        self._render()
+
+    def update(self, message: str) -> None:
+        """Update spinner message.
+
+        Args:
+            message: New message
+        """
+        self.message = message
+        self._render()
+
+    def _render(self) -> None:
+        """Render spinner frame."""
+        if not sys.stdout.isatty():
+            return
+
+        frame = self.frames[self.current_frame]
+        frame_colored = self.formatter.colorize(frame, Color.CYAN)
+
+        line = f"\r{frame_colored} {self.message}"
+        sys.stdout.write(line)
+        sys.stdout.flush()
+
+        self.current_frame = (self.current_frame + 1) % len(self.frames)
+
+    def stop(self, final_message: Optional[str] = None) -> None:
+        """Stop spinner.
+
+        Args:
+            final_message: Final message to display
+        """
+        self.running = False
+
+        if final_message:
+            sys.stdout.write(f"\r{final_message}\n")
+        else:
+            sys.stdout.write("\r" + " " * (len(self.message) + 2) + "\r")
+
+        sys.stdout.flush()
+
+
+def format_error_details(
+    error: Exception,
+    formatter: Optional[OutputFormatter] = None
+) -> str:
+    """Format error with details.
+
+    Args:
+        error: Exception to format
+        formatter: Output formatter
+
+    Returns:
+        Formatted error message
+    """
+    fmt = formatter or OutputFormatter()
+
+    error_type = fmt.colorize(type(error).__name__, Color.RED, bold=True)
+    error_msg = str(error)
+
+    result = f"{error_type}: {error_msg}"
+
+    if hasattr(error, "__dict__"):
+        details = {k: v for k, v in error.__dict__.items() if not k.startswith("_")}
+        if details:
+            result += "\n\n" + fmt.heading("Details:", level=3)
+            result += "\n" + fmt.json_tree(details, indent=1)
+
+    return result

pygeai_orchestration/cli/geai_orch.py

@@ -0,0 +1,270 @@
+import sys
+import logging
+from typing import List, Optional
+
+from pygeai_orchestration.core.utils import get_logger
+from pygeai_orchestration.cli.commands.base import base_commands, base_options
+from pygeai_orchestration.cli.commands import ArgumentsEnum, Command
+from pygeai.cli.parsers import CommandParser
+from pygeai_orchestration.cli.texts.help import CLI_USAGE
+from pygeai_orchestration.cli.error_handler import ErrorHandler, ExitCode
+
+logger = get_logger()
+from pygeai.core.base.session import get_session
+from pygeai.core.common.exceptions import (
+    UnknownArgumentError,
+    MissingRequirementException,
+    WrongArgumentError,
+)
+from pygeai.core.utils.console import Console
+
+
+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-orch CLI application.
+
+    :return: int - Exit code indicating success or error.
+    """
+    try:
+        driver = CLIDriver()
+        return driver.main()
+    except MissingRequirementException as e:
+        error_msg = ErrorHandler.handle_missing_requirement(str(e))
+        Console.write_stderr(error_msg)
+        return ExitCode.MISSING_REQUIREMENT
+
+
+class CLIDriver:
+    """
+    Main CLI driver for the geai-orch command-line interface.
+
+    The CLIDriver orchestrates command parsing, execution, and error handling
+    for all geai-orch 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, credentials_file=None) -> None:
+        """
+        Initialize the CLI driver with optional session and credentials file.
+
+        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.
+        :param credentials_file: Optional path to custom credentials file.
+        """
+        from pygeai.core.common.config import get_settings
+
+        arguments = sys.argv
+
+        if credentials_file or "--credentials" in arguments or "--creds" in arguments:
+            if not credentials_file:
+                credentials_file = self._get_credentials_file(arguments)
+            get_settings(credentials_file=credentials_file)
+            logger.debug(f"Using custom credentials file: {credentials_file}")
+
+        if "-a" in arguments or "--alias" in arguments:
+            alias = self._get_alias(arguments)
+            session = get_session(alias)
+
+        self.session = get_session("default") if session is None else session
+
+    def _get_alias(self, arguments: List[str]) -> str:
+        """
+        Retrieves and removes alias and alias flag from argument list.
+
+        :param arguments: List[str] - Command line arguments.
+        :return: str - The alias value.
+        :raises MissingRequirementException: If alias flag is present but no value provided.
+        """
+        alias_index = None
+
+        if "-a" in arguments:
+            alias_index = arguments.index("-a")
+        elif "--alias" in arguments:
+            alias_index = arguments.index("--alias")
+
+        try:
+            _ = arguments.pop(alias_index)
+            alias = arguments.pop(alias_index)
+            return alias
+        except IndexError:
+            Console.write_stderr(
+                "-a/--alias option requires an alias. Please provide a valid alias after the option"
+            )
+            raise MissingRequirementException("Couldn't find a valid alias in parameter list.")
+
+    def _get_credentials_file(self, arguments: List[str]) -> str:
+        """
+        Retrieves and removes credentials file path and flag from argument list.
+
+        :param arguments: List[str] - Command line arguments.
+        :return: str - The credentials file path.
+        :raises MissingRequirementException: If credentials flag is present but no value provided.
+        """
+        creds_index = None
+
+        if "--credentials" in arguments:
+            creds_index = arguments.index("--credentials")
+        elif "--creds" in arguments:
+            creds_index = arguments.index("--creds")
+
+        try:
+            _ = arguments.pop(creds_index)
+            credentials_file = arguments.pop(creds_index)
+            return credentials_file
+        except IndexError:
+            Console.write_stderr(
+                "--creds/--credentials option requires a file path. Please provide a valid path after the option."
+            )
+            raise MissingRequirementException("Couldn't find a valid path in parameter list.")
+
+    def main(self, args: Optional[List[str]] = None) -> int:
+        """
+        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:
+            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-orch 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("Command completed successfully")
+            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:
+            error_msg = ErrorHandler.handle_missing_requirement(str(e))
+            Console.write_stderr(error_msg)
+            return ExitCode.MISSING_REQUIREMENT
+        except KeyboardInterrupt:
+            message = ErrorHandler.handle_keyboard_interrupt()
+            Console.write_stdout(message)
+            return ExitCode.KEYBOARD_INTERRUPT
+        except Exception as e:
+            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]):
+        """
+        Process a command by either executing it or identifying subcommands.
+
+        If the command has no action associated with it, it means it has subcommands,
+        so it must be parsed again to identify it.
+
+        :param command: Command - The command to process
+        :param arguments: list[str] - Additional arguments for the command
+        """
+        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)