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

gllm_core/schema/component.pyi

@@ -0,0 +1,205 @@
+from gllm_core.event.event_emitter import EventEmitter as EventEmitter
+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 gllm_core.utils.main_method_resolver import MainMethodResolver as MainMethodResolver
+from pydantic import BaseModel as BaseModel
+from typing import Any, Callable
+
+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.
+
+    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.
+    '''
+    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 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.
+        """
+    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:
+        """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.
+        """

gllm_core/schema/event.py

@@ -0,0 +1,50 @@
+"""Defines the Event schema, which represents an event emitted by the system.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field, field_serializer
+
+from gllm_core.constants import EventLevel, EventType
+
+
+class Event(BaseModel):
+    """A data class to store an event attributes.
+
+    Attributes:
+        id (str): The ID of the event. Defaults to None.
+        value (str | dict[str, Any]): The value of the event. Defaults to an empty string.
+        level (EventLevel): The severity level of the event. Defaults to EventLevel.INFO.
+        type (str): The type of the event. Defaults to EventType.RESPONSE.
+        timestamp (datetime): The timestamp of the event. Defaults to the current timestamp.
+        metadata (dict[str, Any]): The metadata of the event. Defaults to an empty dictionary.
+    """
+
+    id: str | None = None
+    value: str | dict[str, Any] = ""
+    level: EventLevel = EventLevel.INFO
+    type: str = EventType.RESPONSE.value
+    timestamp: datetime = Field(default_factory=datetime.now)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @field_serializer("level")
+    def serialize_level(self, level: EventLevel) -> str:
+        """Serializes an EventLevel object into its string representation.
+
+        This method serializes the given EventLevel object by returning its name as a string.
+
+        Args:
+            level (EventLevel): The EventLevel object to be serialized.
+
+        Returns:
+            str: The name of the EventLevel object.
+        """
+        return level.name

gllm_core/schema/event.pyi

@@ -0,0 +1,33 @@
+from datetime import datetime
+from gllm_core.constants import EventLevel as EventLevel, EventType as EventType
+from pydantic import BaseModel
+from typing import Any
+
+class Event(BaseModel):
+    """A data class to store an event attributes.
+
+    Attributes:
+        id (str): The ID of the event. Defaults to None.
+        value (str | dict[str, Any]): The value of the event. Defaults to an empty string.
+        level (EventLevel): The severity level of the event. Defaults to EventLevel.INFO.
+        type (str): The type of the event. Defaults to EventType.RESPONSE.
+        timestamp (datetime): The timestamp of the event. Defaults to the current timestamp.
+        metadata (dict[str, Any]): The metadata of the event. Defaults to an empty dictionary.
+    """
+    id: str | None
+    value: str | dict[str, Any]
+    level: EventLevel
+    type: str
+    timestamp: datetime
+    metadata: dict[str, Any]
+    def serialize_level(self, level: EventLevel) -> str:
+        """Serializes an EventLevel object into its string representation.
+
+        This method serializes the given EventLevel object by returning its name as a string.
+
+        Args:
+            level (EventLevel): The EventLevel object to be serialized.
+
+        Returns:
+            str: The name of the EventLevel object.
+        """

gllm_core/schema/schema_generator.py

@@ -0,0 +1,150 @@
+"""Utility for generating Pydantic models from component methods.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, get_type_hints
+
+from pydantic import BaseModel, ConfigDict, create_model
+
+from gllm_core.utils.analyzer import analyze_method
+
+
+def generate_params_model(method: Callable, class_name: str) -> type[BaseModel]:
+    """Generate a Pydantic model representing a component method signature.
+
+    The generated class is named `{class_name}Params` and contains one field for
+    every parameter in `method`. The first `self` parameter is ignored, `*args` are
+    skipped entirely, and `**kwargs` trigger `extra="allow"` to permit arbitrary
+    keyword arguments at runtime.
+
+    For legacy `_run` methods with only `**kwargs`, this function will use
+    RunAnalyzer to infer parameters from the method body usage patterns.
+
+    Args:
+        method (Callable): Method whose signature should be represented.
+        class_name (str): Component class name used to derive the generated model name.
+
+    Returns:
+        type[BaseModel]: A Pydantic `BaseModel` subclass describing the method's
+            parameters.
+
+    Example:
+        ```python
+        class_name = "TextProcessor"
+
+        def process(self, text: str, count: int = 5) -> str:
+            return text * count
+
+        Model = generate_params_model(process, class_name)
+        assert Model.__name__ == "TextProcessorParams"
+        assert Model(text="hello", count=2).model_dump() == {"text": "hello", "count": 2}
+        ```
+    """
+    signature = inspect.signature(method)
+
+    non_self_params = [param for param in signature.parameters.values() if param.name != "self"]
+
+    if len(non_self_params) == 1 and non_self_params[0].kind == inspect.Parameter.VAR_KEYWORD:
+        return _generate_from_analyzer(method, class_name)
+
+    return _generate_from_signature(method, class_name)
+
+
+def _generate_from_signature(method: Callable, class_name: str) -> type[BaseModel]:
+    """Generate model using method signature analysis.
+
+    This function is used for modern methods with explicit parameter annotations.
+
+    Args:
+        method (Callable): Method whose signature should be represented.
+        class_name (str): Component class name used to derive the generated model name.
+
+    Returns:
+        type[BaseModel]: A Pydantic `BaseModel` subclass describing the method's
+            parameters.
+    """
+    signature = inspect.signature(method)
+
+    try:
+        type_hints = get_type_hints(method)
+    except Exception:  # pragma: no cover - defensive fallback
+        type_hints = {}
+
+    fields: dict[str, tuple[type[Any], Any]] = {}
+    extra_setting = "forbid"
+
+    for param_name, param in signature.parameters.items():
+        if param_name == "self":
+            continue
+        if param.kind == inspect.Parameter.VAR_POSITIONAL:
+            continue
+        if param.kind == inspect.Parameter.VAR_KEYWORD:
+            extra_setting = "allow"
+            continue
+
+        annotation = type_hints.get(param_name, Any)
+        if param.default is inspect.Parameter.empty:
+            fields[param_name] = (annotation, ...)
+        else:
+            fields[param_name] = (annotation, param.default)
+
+    model_name = f"{class_name}Params"
+    return create_model(  # type: ignore[call-overload]
+        model_name,
+        __config__=ConfigDict(extra=extra_setting, arbitrary_types_allowed=True),
+        **fields,
+    )
+
+
+def _generate_from_analyzer(method: Callable, class_name: str) -> type[BaseModel]:
+    """Generate model using RunAnalyzer to infer parameters from method body.
+
+    This is used for legacy `_run` methods that only have `**kwargs` in their signature
+    but use specific parameters within the method body.
+
+    Args:
+        method (Callable): Method whose signature should be represented.
+        class_name (str): Component class name used to derive the generated model name.
+
+    Returns:
+        type[BaseModel]: A Pydantic `BaseModel` subclass describing the method's
+            parameters.
+    """
+
+    class MockClass:
+        pass
+
+    MockClass._run = method
+    config_dict = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+
+    try:
+        profile = analyze_method(MockClass, method)
+
+        fields: dict[str, tuple[type[Any], Any]] = {}
+
+        for param_name in profile.arg_usages.required:
+            fields[param_name] = (Any, ...)
+
+        for param_name in profile.arg_usages.optional:
+            fields[param_name] = (Any, None)
+
+        model_name = f"{class_name}Params"
+        return create_model(  # type: ignore[call-overload]
+            model_name,
+            __config__=config_dict,
+            **fields,
+        )
+    except Exception:
+        model_name = f"{class_name}Params"
+        return create_model(  # type: ignore[call-overload]
+            model_name,
+            __config__=config_dict,
+        )

gllm_core/schema/schema_generator.pyi

@@ -0,0 +1,35 @@
+from gllm_core.utils.analyzer import analyze_method as analyze_method
+from pydantic import BaseModel as BaseModel
+from typing import Callable
+
+def generate_params_model(method: Callable, class_name: str) -> type[BaseModel]:
+    '''Generate a Pydantic model representing a component method signature.
+
+    The generated class is named `{class_name}Params` and contains one field for
+    every parameter in `method`. The first `self` parameter is ignored, `*args` are
+    skipped entirely, and `**kwargs` trigger `extra="allow"` to permit arbitrary
+    keyword arguments at runtime.
+
+    For legacy `_run` methods with only `**kwargs`, this function will use
+    RunAnalyzer to infer parameters from the method body usage patterns.
+
+    Args:
+        method (Callable): Method whose signature should be represented.
+        class_name (str): Component class name used to derive the generated model name.
+
+    Returns:
+        type[BaseModel]: A Pydantic `BaseModel` subclass describing the method\'s
+            parameters.
+
+    Example:
+        ```python
+        class_name = "TextProcessor"
+
+        def process(self, text: str, count: int = 5) -> str:
+            return text * count
+
+        Model = generate_params_model(process, class_name)
+        assert Model.__name__ == "TextProcessorParams"
+        assert Model(text="hello", count=2).model_dump() == {"text": "hello", "count": 2}
+        ```
+    '''