gllm-core-binary 0.3.23b3__py3-none-any.whl → 0.4.4__py3-none-any.whl

gllm_core/schema/component.py

@@ -10,12 +10,9 @@ References:
 
 from __future__ import annotations
 
-import ast
 import inspect
 import logging
-import textwrap
 import warnings
-from abc import ABC, abstractmethod
 from functools import lru_cache
 from traceback import format_exc
 from typing import TYPE_CHECKING, Any, Callable
@@ -23,25 +20,83 @@ from typing import TYPE_CHECKING, Any, Callable
 if TYPE_CHECKING:
     from gllm_core.event.event_emitter import EventEmitter
 
-from gllm_core.utils.analyzer import MethodSignature, ParameterInfo, ParameterKind, RunAnalyzer, RunProfile
+
+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(ABC):
+
+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.
 
-    Example:
-    ```python
-    class MyComponent(Component):
-        _default_log_level = logging.INFO
+    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!"
+           ```
 
-        def _run(self, **kwargs: Any) -> Any:
-            return "Hello, World!"
-    ```
+        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.
@@ -52,12 +107,100 @@ class Component(ABC):
             **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 (int): The default log level for the component. Defaults to DEBUG.
-        _logger (logging.Logger): The logger instance for the component.
     """
 
     _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.
@@ -94,28 +237,92 @@ class Component(ABC):
     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 a process
-        defined in the `_run` method, and emits the resulting output if the EventEmitter is provided.
+        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 `_run` method.
+            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)
 
-        output = await self._run(**kwargs)
+        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.
 
@@ -147,8 +354,10 @@ class Component(ABC):
 
         if input_dict:
             message += " Processing input: "
+            handler = binary_handler_factory(BinaryHandlingStrategy.SHOW_SIZE)
             for key, value in input_dict.items():
-                message += f"\n    - {key}: {value!r}"
+                formatted_value = handler(value) if isinstance(value, bytes) else value
+                message += f"\n    - {key}: {formatted_value!r}"
 
         return message
 
@@ -164,17 +373,21 @@ class Component(ABC):
         Returns:
             str: A formatted event message string representing the output data.
         """
-        message = f"[Finished {self.__class__.__name__!r}] Successfully produced output:\n{output!r}"
+        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
 
-    @abstractmethod
     async def _run(self, **kwargs: Any) -> Any:
         """Defines the core process logic to be implemented by subclasses.
 
-        This abstract method must be implemented in a subclass to define the specific process that will be executed.
+        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.
 
@@ -227,11 +440,7 @@ class Component(ABC):
         """
         try:
             method = cls._run
-            source = inspect.getsource(method)
-            tree = ast.parse(textwrap.dedent(source))
-            analyzer = RunAnalyzer(cls)
-            analyzer.visit(tree)
-            return analyzer.profile
+            return analyze_method(cls, method)
         except Exception as e:
             warnings.warn(
                 f"Failed to analyze the _run method: {e}.\n{format_exc()}",

gllm_core/schema/component.pyi

@@ -1,25 +1,71 @@
-import abc
-from abc import ABC
 from gllm_core.event.event_emitter import EventEmitter as EventEmitter
-from gllm_core.utils.analyzer import MethodSignature as MethodSignature, ParameterInfo as ParameterInfo, ParameterKind as ParameterKind, RunAnalyzer as RunAnalyzer, RunProfile as RunProfile
+from gllm_core.schema.schema_generator import generate_params_model as generate_params_model
+from gllm_core.schema.tool import Tool as Tool, tool as tool
+from gllm_core.utils import BinaryHandlingStrategy as BinaryHandlingStrategy, binary_handler_factory as binary_handler_factory
+from gllm_core.utils.analyzer import MethodSignature as MethodSignature, ParameterInfo as ParameterInfo, ParameterKind as ParameterKind, RunProfile as RunProfile, analyze_method as analyze_method
 from gllm_core.utils.logger_manager import LoggerManager as LoggerManager
-from typing import Any
+from gllm_core.utils.main_method_resolver import MainMethodResolver as MainMethodResolver
+from pydantic import BaseModel as BaseModel
+from typing import Any, Callable
 
-class Component(ABC, metaclass=abc.ABCMeta):
+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.
+    """
+
+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.
 
-    Example:
-    ```python
-    class MyComponent(Component):
-        _default_log_level = logging.INFO
+    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
 
-        def _run(self, **kwargs: Any) -> Any:
-            return "Hello, World!"
-    ```
+               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.
@@ -30,21 +76,122 @@ class Component(ABC, metaclass=abc.ABCMeta):
             **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 (int): The default log level for the component. Defaults to DEBUG.
-        _logger (logging.Logger): The logger instance for the component.
     '''
+    def __init_subclass__(cls, **kwargs) -> None:
+        """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.
+        """
+    @classmethod
+    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.
+        """
+    @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)
+            ```
+        '''
     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 a process
-        defined in the `_run` method, and emits the resulting output if the EventEmitter is provided.
+        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 `_run` method.
+            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.
+        """
+    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__.
         """
     @property
     def run_profile(self) -> RunProfile: