gllm-core-binary 0.4.4__py3-none-manylinux_2_31_x86_64.whl

gllm_core/schema/component.py

@@ -0,0 +1,546 @@
+"""Defines an abstract base class for all components used throughout the Gen AI applications.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import warnings
+from functools import lru_cache
+from traceback import format_exc
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from gllm_core.event.event_emitter import EventEmitter
+
+
+from pydantic import BaseModel
+
+from gllm_core.schema.schema_generator import generate_params_model
+from gllm_core.schema.tool import Tool, tool
+from gllm_core.utils import BinaryHandlingStrategy, binary_handler_factory
+from gllm_core.utils.analyzer import MethodSignature, ParameterInfo, ParameterKind, RunProfile, analyze_method
+from gllm_core.utils.logger_manager import LoggerManager
+from gllm_core.utils.main_method_resolver import MainMethodResolver
+
+
+def main(method: Callable) -> Callable:
+    """Decorate a Component method as the async main entrypoint.
+
+    Usage:
+        Declare the coroutine that should act as the primary execution path
+        for a `Component` subclass. The decorated coroutine will be resolved by
+        `Component.run()` unless another subclass overrides the decoration.
+
+    Args:
+        method (Callable): Coroutine to mark as the main entrypoint.
+
+    Returns:
+        Callable: The same coroutine that is passed to the decorator. The decorator only marks the method as the main
+            entrypoint. It does not wrap or change its behavior or signature.
+
+    Raises:
+        TypeError: If the decorated callable is not asynchronous.
+    """
+    actual_method = method.__func__ if isinstance(method, (classmethod, staticmethod)) else method
+
+    if not inspect.iscoroutinefunction(actual_method):
+        method_name = getattr(actual_method, "__name__", "unknown")
+        raise TypeError(f"Main method {method_name!r} must be asynchronous")
+    method.__is_main__ = True
+    return method
+
+
+class Component:
+    """An abstract base class for all components used throughout the Gen AI applications.
+
+    Every instance of Component has access to class-level `_default_log_level` and `_logger`, as detailed below.
+    For components that require high observability, it is recommended to set `_default_log_level` to `logging.INFO`
+    or higher.
+
+    Defining Custom Components:
+        There are two ways to define the main execution logic for a component:
+
+        1. **Using the @main decorator (Recommended)**:
+           Decorate an async method with `@main` to mark it as the primary entrypoint.
+           This is the preferred approach as it provides explicit control over the main method.
+
+           ```python
+           class MyComponent(Component):
+               _default_log_level = logging.INFO
+
+               @main
+               async def execute(self, **kwargs: Any) -> Any:
+                   return "Hello from @main!"
+           ```
+
+        2. **Implementing _run method (Deprecated)**:
+           Override the abstract `_run` method. This is the traditional approach and still supported.
+
+           ```python
+           class MyComponent(Component):
+               _default_log_level = logging.INFO
+
+               async def _run(self, **kwargs: Any) -> Any:
+                   return "Hello, World!"
+           ```
+
+        The `run()` method resolves the main entrypoint using the following precedence:
+        1. Method decorated with @main in the current class.
+        2. Method decorated with @main in the nearest ancestor class.
+        3. Method named in __main_method__ property.
+        4. The _run method (with deprecation warning).
+
+    Attributes:
+        run_profile (RunProfile): The profile of the `_run` method.
+            This property is used by `Pipeline` to analyze the input requirements of the component.
+            In most cases, unless you are working with `Pipeline` and `PipelineStep`s, you will not need to use this
+            property.
+
+            **Do not override this property in your subclass.**
+
+            You also do not need to write this attribute in your component's docstring.
+    """
+
+    _default_log_level = logging.DEBUG
+
+    def __init_subclass__(cls, **kwargs):
+        """Hook called when a subclass is created.
+
+        This validates the __main_method__ property and checks for multiple @main decorators
+        within the current class definition. Uses MainMethodResolver for consistent validation logic.
+
+        Note: Multiple inheritance conflicts are intentionally deferred to runtime (get_main())
+        to allow class definition to succeed.
+
+        Raises:
+            AttributeError: If __main_method__ refers to a non-existent method.
+            TypeError: If multiple methods are decorated with @main in the same class.
+        """
+        super().__init_subclass__(**kwargs)
+
+        MainMethodResolver.validate_class(cls)
+
+    @classmethod
+    @lru_cache(maxsize=None)
+    def get_main(cls) -> Callable | None:
+        """Return the resolved main coroutine for this Component class.
+
+        This method resolves the main method for the Component class following
+        the precedence rules:
+        1. Most derived coroutine decorated with `@main`.
+        2. Method named by `__main_method__`.
+        3. `_run` coroutine as a deprecated fallback.
+
+        Results are cached for performance.
+
+        Returns:
+            Callable | None: The coroutine that will be executed by `run()` or
+                `None` when no entrypoint can be determined.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+        """
+        return MainMethodResolver(cls).resolve()
+
+    @classmethod
+    @lru_cache(maxsize=None)
+    def _get_input_params_model(cls) -> type[BaseModel] | None:
+        """Generate and cache the input-parameter model for this component class.
+
+        Returns:
+            type[BaseModel] | None: A Pydantic model describing the component's
+                input parameters, or `None` when no main method can be resolved or the
+                model generation fails.
+        """
+        main_method = cls.get_main() or cls._run
+
+        try:
+            return generate_params_model(main_method, cls.__name__)
+        except Exception:  # pragma: no cover - defensive fallback
+            logging.getLogger(__name__).exception("Failed to generate input params model for %s", cls.__name__)
+
+    @property
+    def input_params(self) -> type[BaseModel] | None:
+        """Return the Pydantic model describing this component's main method input parameters.
+
+        Returns:
+            type[BaseModel] | None: The cached model that mirrors the signature of
+                the resolved main method, or `None` if no main method can be
+                determined.
+
+        Examples:
+            ```python
+            from pydantic import ValidationError
+
+            component = SomeComponent()
+            ParamsModel = component.input_params
+            assert ParamsModel.__name__ == "SomeComponentParams"
+            fields = list(ParamsModel.model_fields)
+
+            # Validation with valid params
+            params = ParamsModel(text="hello")
+
+            # Validation catches missing required fields
+            try:
+                invalid_params = ParamsModel()  # Missing required 'text' field
+            except ValidationError as e:
+                print(f"Validation failed: {e.error_count()} errors")
+
+            # Argument construction
+            payload = params.model_dump()
+            result = await component.run(**payload)
+            ```
+        """
+        return self.__class__._get_input_params_model()
+
+    @property
+    def _logger(self) -> logging.Logger:
+        """Get a logger instance configured for this component class.
+
+        The logger uses the class name as the logger name and applies
+        the configured log level for this component class.
+
+        Returns:
+            logging.Logger: A configured logger instance.
+        """
+        if not hasattr(self, "_logger_instance"):
+            logger = LoggerManager().get_logger(self.__class__.__name__)
+            logger.setLevel(self.__class__._default_log_level)
+            self._logger_instance = logger
+
+        return self._logger_instance
+
+    @_logger.setter
+    def _logger(self, logger: logging.Logger) -> None:
+        """Set a custom logger instance for this component.
+
+        Args:
+            logger (logging.Logger): The logger instance to use.
+
+        Raises:
+            TypeError: If `logger` is not an instance of `logging.Logger`.
+        """
+        if not isinstance(logger, logging.Logger):
+            raise TypeError("_logger must be an instance of logging.Logger")
+
+        logger.setLevel(self.__class__._default_log_level)
+        self._logger_instance = logger
+
+    async def run(self, **kwargs: Any) -> Any:
+        """Runs the operations defined for the component.
+
+        This method emits the provided input arguments using an EventEmitter instance if available, executes the
+        resolved main method, and emits the resulting output if the EventEmitter is provided.
+
+        The main method is resolved using the following precedence:
+        1. Method decorated with @main in the current class.
+        2. Method decorated with @main in the nearest ancestor class.
+        3. Method named in __main_method__ property.
+        4. The _run method (with deprecation warning).
+
+        Args:
+            **kwargs (Any): A dictionary of arguments to be processed. May include an `event_emitter`
+                key with an EventEmitter instance.
+
+        Returns:
+            Any: The result of the resolved main method.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+            AttributeError: If __main_method__ refers to a non-existent method.
+        """
+        event_emitter = kwargs.get("event_emitter")
+
+        input_event = self._format_input_event(kwargs)
+        await self._log_io_event(input_event, event_emitter)
+
+        main_method = self.get_main()
+        if main_method:
+            output = await main_method(self, **kwargs)
+        else:
+            self._logger.warning(
+                "_run method is deprecated and will be removed in a future release.\n"
+                "Use the `@main` decorator instead."
+            )
+            output = await self._run(**kwargs)
+
+        output_event = self._format_output_event(output)
+        await self._log_io_event(output_event, event_emitter)
+
+        return output
+
+    def as_tool(self, name: str | None = None, description: str | None = None, title: str | None = None) -> Tool:
+        """Convert the component's main method into a `Tool` instance.
+
+        Example:
+            ```python
+            from gllm_core.schema import Component, main
+
+            class MyComponent(Component):
+                @main
+                async def my_method(self, param: str) -> str:
+                    return param
+
+            component = MyComponent()
+            tool = component.as_tool()
+            ```
+
+        Args:
+            name (str | None, optional): Identifier for the resulting tool. Defaults to the component class name.
+            description (str | None, optional): Summary of the tool's behavior. Defaults to None, in which case the
+                main method's docstring is used.
+            title (str | None, optional): Optional display title for the tool. Defaults to None, in which case the
+                component's class name is used.
+
+        Returns:
+            Tool: The tool wrapping the component's main method.
+
+        Raises:
+            RuntimeError: If the component does not declare a main method using @main or __main_method__.
+        """
+        main_method = self.get_main()
+        if main_method is None or main_method is self.__class__._run:
+            raise RuntimeError(
+                "Component main method is not declared. Use @main or __main_method__ before converting to a tool."
+            )
+
+        bound_main = main_method.__get__(self, self.__class__)
+
+        tool_name = name or self.__class__.__name__
+        tool_decorator = tool(name=tool_name, description=description, title=title)
+        component_tool = tool_decorator(bound_main)
+
+        if not isinstance(component_tool, Tool):  # pragma: no cover - Defensive: decorator should always return Tool
+            raise TypeError("Failed to convert component main method into a Tool instance.")
+
+        return component_tool
+
+    async def _log_io_event(self, event_message: str, event_emitter: EventEmitter | None = None) -> None:
+        """Logs an event message and emits it via the event emitter if available.
+
+        This helper method encapsulates the pattern of logging a message and then emitting
+        the same message through an event emitter when available.
+
+        Args:
+            event_message (str): The message to log and emit.
+            event_emitter (EventEmitter | None, optional): An event emitter instance. Defaults to None.
+        """
+        if event_message:
+            self._logger.log(self.__class__._default_log_level, event_message)
+            if event_emitter:
+                await event_emitter.emit(event_message)
+
+    def _format_input_event(self, input_dict: dict) -> str:
+        """Formats the input data into an event message string.
+
+        This method constructs a formatted event message that details the input data being processed.
+        It includes the class name and each key-value pair from the input dictionary.
+
+        Args:
+            input_dict (dict): A dictionary containing the input data to be emitted.
+
+        Returns:
+            str: A formatted event message string representing the input data.
+        """
+        message = f"[Start {self.__class__.__name__!r}]"
+
+        if input_dict:
+            message += " Processing input: "
+            handler = binary_handler_factory(BinaryHandlingStrategy.SHOW_SIZE)
+            for key, value in input_dict.items():
+                formatted_value = handler(value) if isinstance(value, bytes) else value
+                message += f"\n    - {key}: {formatted_value!r}"
+
+        return message
+
+    def _format_output_event(self, output: Any) -> str:
+        """Formats the output data into an event message string.
+
+        This method constructs a formatted event message that details the output produced by the process.
+        It includes the class name and the output data.
+
+        Args:
+            output (Any): The output data to be emitted.
+
+        Returns:
+            str: A formatted event message string representing the output data.
+        """
+        handler = binary_handler_factory(BinaryHandlingStrategy.SHOW_SIZE)
+        formatted_output = handler(output) if isinstance(output, bytes) else output
+        message = f"[Finished {self.__class__.__name__!r}] Successfully produced output:\n{formatted_output!r}"
+        return message
+
+    async def _run(self, **kwargs: Any) -> Any:
+        """Defines the core process logic to be implemented by subclasses.
+
+        This method can be implemented in a subclass to define the specific process that will be executed.
+        It is called by the `run` method and is responsible for handling the provided input arguments and producing
+        an output.
+
+        Deprecation:
+            This method is deprecated and will be removed in a future release. Use the `@main` decorator instead.
+
+        Args:
+            **kwargs (Any): A dictionary of arguments required for the process.
+
+        Returns:
+            Any: The result of the process.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+        raise NotImplementedError
+
+    # If you are looking to implement a `Component`, you do not need to worry about the methods below. Simply implement
+    # `_run` method in your subclass; you are good to go.
+    #
+    # The methods below are used to analyze the `_run` method and retrieve its profile.
+    #
+    # The addition of profiling-related methods to our `Component` class is crucial for achieving effective input
+    # validation in our `Pipeline`. By dynamically analyzing the `_run` method, we can generate a detailed profile of
+    # its input requirements. This profile enables the pipeline to perform comprehensive input validation, ensuring that
+    # all components receive the correct inputs they need to function properly.
+    #
+    # This approach enhances the robustness and reliability of our pipeline while reducing the need for manual
+    # configuration and documentation of input requirements.
+
+    @property
+    def run_profile(self) -> RunProfile:
+        """Analyzes the `_run` method and retrieves its profile.
+
+        This property method analyzes the `_run` method of the class to generate a `RunProfile` object.
+        It also updates the method signatures for methods that fully utilize the arguments.
+
+        Returns:
+            RunProfile: The profile of the `_run` method, including method signatures for full-pass argument usages.
+        """
+        profile = self._analyze_run_method()
+        for method_name in profile.full_pass_methods:
+            profile.method_signatures[method_name] = self._get_method_signature(method_name)
+        return profile
+
+    @classmethod
+    @lru_cache
+    def _analyze_run_method(cls) -> RunProfile:
+        """Analyzes the `_run` method and retrieves its profile.
+
+        This method inspects the `_run` method of the class, parses its source code into an AST,
+        and uses the `RunAnalyzer` to visit the AST nodes and generate a `RunProfile` object.
+
+        Returns:
+            RunProfile: The profile of the `_run` method, including method signatures for full-pass argument usages.
+        """
+        try:
+            method = cls._run
+            return analyze_method(cls, method)
+        except Exception as e:
+            warnings.warn(
+                f"Failed to analyze the _run method: {e}.\n{format_exc()}",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            return RunProfile()
+
+    @classmethod
+    def _get_method_signature(cls, method_name: str) -> MethodSignature:
+        """Retrieves the method signature for a given method name.
+
+        This method uses the `inspect` module to get the signature of the specified method
+        and constructs a `MethodSignature` object containing parameter information and
+        whether the method is asynchronous.
+
+        Known limitations:
+        1. Nested functions or external methods are not supported.
+        2. Nested **kwargs are not supported.
+
+        Args:
+            method_name (str): The name of the method to retrieve the signature for.
+
+        Returns:
+            MethodSignature: An object containing the method's signature details.
+        """
+        if "." in method_name:
+            class_name, method_name = method_name.rsplit(".", 1)
+            if class_name == cls.__name__:
+                method = getattr(cls, method_name, None)
+            else:
+                # This is a nested function or external method, we can't get its signature
+                return MethodSignature(parameters={}, is_async=False)
+        else:
+            method = getattr(cls, method_name, None)
+
+        if method is None:
+            # Try to find the function in the global scope
+            method = cls._find_global_function(method_name)
+
+        if method is None:
+            # If we still can't find the method, return a default signature
+            return MethodSignature(parameters={}, is_async=False)
+
+        return cls._create_method_signature(method)
+
+    @staticmethod
+    @lru_cache
+    def _find_global_function(func_name: str) -> Callable | None:
+        """Finds a global function by name.
+
+        This method searches for a function with the given name in the global scope.
+        If the function is not found in the global scope, it searches in the imported modules.
+
+        Args:
+            func_name (str): The name of the function to find.
+
+        Returns:
+            Callable | None: The function if found, otherwise None.
+        """
+        # Get the global scope
+        globals_dict = globals()
+
+        # Try to find the function in the global scope
+        if func_name in globals_dict and callable(globals_dict[func_name]):
+            return globals_dict[func_name]
+
+        # If not found, try to find it in imported modules
+        for value in globals_dict.values():
+            if inspect.ismodule(value):
+                func = getattr(value, func_name, None)
+                if callable(func):
+                    return func
+
+        return None
+
+    @staticmethod
+    def _create_method_signature(method: Callable) -> MethodSignature:
+        """Creates a method signature object from the provided method.
+
+        Args:
+            method (Callable): The method to create a signature for.
+
+        Returns:
+            MethodSignature: An object containing the method's signature details.
+        """
+        sig = inspect.signature(method)
+        params = sig.parameters
+
+        is_instance_method = list(params.keys())[0] == "self" if params else False
+
+        return MethodSignature(
+            parameters={
+                name: ParameterInfo(
+                    kind=ParameterKind(str(param.kind).rsplit(".", maxsplit=1)[-1].lower()),
+                    default=str(param.default) if param.default is not inspect.Parameter.empty else None,
+                    annotation=str(param.annotation) if param.annotation is not inspect.Parameter.empty else None,
+                )
+                for name, param in params.items()
+                if not (is_instance_method and name == "self")  # Skip 'self' for instance methods
+            },
+            is_async=inspect.iscoroutinefunction(method),
+        )