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

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}
+        ```
+    '''

gllm_core/schema/tool.py

@@ -6,6 +6,7 @@ Authors:
 References:
     [1] https://modelcontextprotocol.io/
 """
+from __future__ import annotations
 
 import asyncio
 import inspect
@@ -268,7 +269,36 @@ class Tool(BaseModel):
     func: Callable | None = Field(default=None)
     is_async: bool = Field(default=False)
 
-    model_config = ConfigDict(populate_by_name=True, arbitrary_types_allowed=True)
+    model_config = ConfigDict(validate_by_name=True, arbitrary_types_allowed=True)
+
+    @classmethod
+    def from_langchain(cls, langchain_tool: Any) -> "Tool":
+        """Create a Tool from a LangChain tool instance.
+
+        Args:
+            langchain_tool (Any): LangChain tool implementation to convert.
+
+        Returns:
+            Tool: Tool instance derived from the LangChain representation.
+        """
+        from gllm_core.adapters.tool import from_langchain_tool  # noqa: PLC0415
+
+        return from_langchain_tool(langchain_tool)
+
+    @classmethod
+    def from_google_adk(cls, function_declaration: Any, func: Callable | None = None) -> "Tool":
+        """Create a Tool from a Google ADK function declaration.
+
+        Args:
+            function_declaration (Any): Google ADK function declaration to convert.
+            func (Callable | None): Optional implementation callable for the tool.
+
+        Returns:
+            Tool: Tool instance derived from the Google ADK definition.
+        """
+        from gllm_core.adapters.tool import from_google_function  # noqa: PLC0415
+
+        return from_google_function(function_declaration, func=func)
 
     @field_validator("input_schema", mode="before")
     @classmethod

gllm_core/schema/tool.pyi

@@ -110,6 +110,27 @@ class Tool(BaseModel):
     is_async: bool
     model_config: Incomplete
     @classmethod
+    def from_langchain(cls, langchain_tool: Any) -> Tool:
+        """Create a Tool from a LangChain tool instance.
+
+        Args:
+            langchain_tool (Any): LangChain tool implementation to convert.
+
+        Returns:
+            Tool: Tool instance derived from the LangChain representation.
+        """
+    @classmethod
+    def from_google_adk(cls, function_declaration: Any, func: Callable | None = None) -> Tool:
+        """Create a Tool from a Google ADK function declaration.
+
+        Args:
+            function_declaration (Any): Google ADK function declaration to convert.
+            func (Callable | None): Optional implementation callable for the tool.
+
+        Returns:
+            Tool: Tool instance derived from the Google ADK definition.
+        """
+    @classmethod
     def validate_input_schema(cls, v: Any):
         """Validate and convert input_schema to JSON Schema dict if it's a Pydantic model.
 

gllm_core/utils/__init__.py

@@ -7,6 +7,7 @@ from gllm_core.utils.concurrency import asyncify, get_default_portal, syncify
 from gllm_core.utils.event_formatter import format_chunk_message, get_placeholder_keys
 from gllm_core.utils.google_sheets import load_gsheets
 from gllm_core.utils.logger_manager import LoggerManager
+from gllm_core.utils.main_method_resolver import MainMethodResolver
 from gllm_core.utils.merger_method import MergerMethod
 from gllm_core.utils.retry import RetryConfig, retry
 from gllm_core.utils.validation import validate_string_enum
@@ -15,6 +16,7 @@ __all__ = [
     "BinaryHandlingStrategy",
     "ChunkMetadataMerger",
     "LoggerManager",
+    "MainMethodResolver",
     "MergerMethod",
     "RunAnalyzer",
     "RetryConfig",

gllm_core/utils/__init__.pyi

@@ -5,8 +5,9 @@ from gllm_core.utils.concurrency import asyncify as asyncify, get_default_portal
 from gllm_core.utils.event_formatter import format_chunk_message as format_chunk_message, get_placeholder_keys as get_placeholder_keys
 from gllm_core.utils.google_sheets import load_gsheets as load_gsheets
 from gllm_core.utils.logger_manager import LoggerManager as LoggerManager
+from gllm_core.utils.main_method_resolver import MainMethodResolver as MainMethodResolver
 from gllm_core.utils.merger_method import MergerMethod as MergerMethod
 from gllm_core.utils.retry import RetryConfig as RetryConfig, retry as retry
 from gllm_core.utils.validation import validate_string_enum as validate_string_enum
 
-__all__ = ['BinaryHandlingStrategy', 'ChunkMetadataMerger', 'LoggerManager', 'MergerMethod', 'RunAnalyzer', 'RetryConfig', 'asyncify', 'get_default_portal', 'binary_handler_factory', 'format_chunk_message', 'get_placeholder_keys', 'load_gsheets', 'syncify', 'retry', 'validate_string_enum']
+__all__ = ['BinaryHandlingStrategy', 'ChunkMetadataMerger', 'LoggerManager', 'MainMethodResolver', 'MergerMethod', 'RunAnalyzer', 'RetryConfig', 'asyncify', 'get_default_portal', 'binary_handler_factory', 'format_chunk_message', 'get_placeholder_keys', 'load_gsheets', 'syncify', 'retry', 'validate_string_enum']

gllm_core/utils/analyzer.py

@@ -10,8 +10,10 @@ References:
 """
 
 import ast
+import inspect
+import textwrap
 from enum import StrEnum
-from typing import Any
+from typing import Any, Callable
 
 from pydantic import BaseModel, Field
 
@@ -230,4 +232,25 @@ class RunAnalyzer(ast.NodeVisitor):
                 return expr.attr
             if isinstance(expr, ast.Constant):
                 return str(expr.value)
+            # Fallback for unknown node types
             return expr.__class__.__name__
+
+
+def analyze_method(cls: type, method: Callable) -> RunProfile:
+    """Analyze a method using RunAnalyzer.
+
+    This function encapsulates the common analysis logic used by both
+    Component._analyze_run_method() and schema_generator._generate_from_analyzer().
+
+    Args:
+        cls (type): The class containing the method (for analyzer context).
+        method (Callable): The method to analyze.
+
+    Returns:
+        RunProfile: The analysis results.
+    """
+    analyzer = RunAnalyzer(cls)
+    source = inspect.getsource(method)
+    tree = ast.parse(textwrap.dedent(source))
+    analyzer.visit(tree)
+    return analyzer.profile

gllm_core/utils/analyzer.pyi

@@ -2,7 +2,7 @@ import ast
 from _typeshed import Incomplete
 from enum import StrEnum
 from pydantic import BaseModel
-from typing import Any
+from typing import Any, Callable
 
 class ParameterKind(StrEnum):
     """Enum representing the different kinds of parameters a method can have."""
@@ -107,3 +107,17 @@ class RunAnalyzer(ast.NodeVisitor):
         Args:
             node (ast.Subscript): The Subscript node to visit.
         '''
+
+def analyze_method(cls, method: Callable) -> RunProfile:
+    """Analyze a method using RunAnalyzer.
+
+    This function encapsulates the common analysis logic used by both
+    Component._analyze_run_method() and schema_generator._generate_from_analyzer().
+
+    Args:
+        cls (type): The class containing the method (for analyzer context).
+        method (Callable): The method to analyze.
+
+    Returns:
+        RunProfile: The analysis results.
+    """

gllm_core/utils/concurrency.py

@@ -125,7 +125,7 @@ def asyncify(
     """
 
     async def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-        return await anyio.to_thread.run_sync(lambda: func(*args, **kwargs), cancellable=cancellable, limiter=limiter)
+        return await anyio.to_thread.run_sync(lambda: func(*args, **kwargs), abandon_on_cancel=cancellable, limiter=limiter)
 
     return _wrapper
 
@@ -179,6 +179,6 @@ def syncify(
 
     def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         p: BlockingPortal = portal if portal is not None else get_default_portal()
-        return p.call(async_func, *args, **kwargs)
+        return p.call(lambda: async_func(*args, **kwargs))
 
     return _wrapper

gllm_core/utils/logger_manager.py

@@ -30,6 +30,13 @@ TEXT_COLOR_MAP = {
     logging.CRITICAL: "bold black on red",
 }
 LOG_FORMAT_KEY = "LOG_FORMAT"
+RICH_CLOSE_TAG = "[/"
+JSON_LOG_FIELDS = ["timestamp", "name", "level", "message"]
+JSON_ERROR_FIELDS_MAP = {
+    "exc_info": "message",
+    "stack_info": "stacktrace",
+    "error_code": "code",
+}
 
 
 class TextRichHandler(RichHandler):
@@ -44,6 +51,8 @@ class TextRichHandler(RichHandler):
         color = TEXT_COLOR_MAP.get(record.levelno, "white")
 
         name, msg = record.name, record.getMessage()
+        msg = msg.replace(RICH_CLOSE_TAG, rf"\{RICH_CLOSE_TAG}")
+
         record.msg = f"[{color}][{name}] {msg}[/]"
         record.args = None
 
@@ -70,6 +79,7 @@ class SimpleRichHandler(logging.StreamHandler):
         """
         color = TEXT_COLOR_MAP.get(record.levelno, "white")
         msg = self.format(record)
+        msg = msg.replace(RICH_CLOSE_TAG, rf"\{RICH_CLOSE_TAG}")
 
         self.console.print(f"[{color}]{msg}[/]", markup=True, highlight=False)
 
@@ -93,17 +103,17 @@ class AppJSONFormatter(JsonFormatter):
             LogRecord: The processed log record.
         """
         record = super().process_log_record(log_record)
+        logged_record = {key: value for key, value in record.items() if key in JSON_LOG_FIELDS}
+        error_payload: dict[str, str] = dict.fromkeys(JSON_ERROR_FIELDS_MAP.values(), "")
 
-        error_payload: dict[str, str] = {}
-
-        for key, new_key in [("exc_info", "message"), ("stack_info", "stacktrace"), ("error_code", "code")]:
-            if value := record.pop(key, None):
+        for key, new_key in JSON_ERROR_FIELDS_MAP.items():
+            if value := record.get(key):
                 error_payload[new_key] = value
 
-        if error_payload:
-            record["error"] = error_payload
+        if any(error_payload.values()):
+            logged_record["error"] = error_payload
 
-        return record
+        return logged_record
 
 
 LOG_FORMAT_HANDLER_MAP = {

gllm_core/utils/logger_manager.pyi

@@ -8,6 +8,9 @@ from rich.logging import RichHandler
 DEFAULT_DATE_FORMAT: str
 TEXT_COLOR_MAP: Incomplete
 LOG_FORMAT_KEY: str
+RICH_CLOSE_TAG: str
+JSON_LOG_FIELDS: Incomplete
+JSON_ERROR_FIELDS_MAP: Incomplete
 
 class TextRichHandler(RichHandler):
     """Custom RichHandler that applies specific colors and log format."""

gllm_core/utils/main_method_resolver.py

@@ -0,0 +1,185 @@
+"""Main method resolver for Component classes.
+
+This module provides the MainMethodResolver class which encapsulates the logic
+for resolving the main entrypoint method for Component subclasses.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from abc import ABC
+from typing import Callable
+
+from gllm_core.utils.logger_manager import LoggerManager
+
+
+class MainMethodResolver:
+    """Resolves the main entrypoint method for Component classes.
+
+    This resolver implements the precedence rules for determining which method
+    should be used as the main entrypoint:
+    1. Method decorated with @main in the most derived class.
+    2. Method named by __main_method__ property.
+    3. _run method (with deprecation warning).
+
+    Attributes:
+        cls (type): The Component class to resolve the main method for.
+    """
+
+    def __init__(self, component_class: type):
+        """Initialize the resolver with a Component class.
+
+        Args:
+            component_class (type): The Component class to resolve the main method for.
+        """
+        self.cls = component_class
+        self._logger = LoggerManager().get_logger(f"MainMethodResolver.{component_class.__name__}")
+
+    @staticmethod
+    def validate_class(component_class: type) -> None:
+        """Validate main method configuration at class definition time.
+
+        This performs early validation that can be done when a Component subclass
+        is defined, before any instances are created or methods are called.
+
+        Validations performed:
+        1. Check that __main_method__ property points to an existing method
+        2. Check that only one @main decorator is used within the same class
+
+        Note: Multiple inheritance conflicts are intentionally NOT checked here,
+        as they are deferred to runtime (get_main()) to allow class definition
+        to succeed.
+
+        Args:
+            component_class (type): The Component class to validate.
+
+        Raises:
+            AttributeError: If __main_method__ refers to a non-existent method.
+            TypeError: If multiple methods are decorated with @main in the same class.
+        """
+        if (method_name := getattr(component_class, "__main_method__", None)) is not None:
+            if not hasattr(component_class, method_name):
+                raise AttributeError(
+                    f"Method {method_name!r} specified in __main_method__ does not exist in {component_class.__name__}"
+                )
+
+        main_methods = []
+        for name, method in component_class.__dict__.items():
+            if callable(method) and hasattr(method, "__is_main__"):
+                main_methods.append(name)
+
+        if len(main_methods) > 1:
+            raise TypeError(f"Multiple main methods defined in {component_class.__name__}: {', '.join(main_methods)}")
+
+    def resolve(self) -> Callable | None:
+        """Resolve the main method following precedence rules.
+
+        Returns:
+            Callable | None: The resolved main method, or None if not found.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+        """
+        if decorated := self._resolve_decorated():
+            self._warn_if_redundant_property()
+            return decorated
+
+        if property_method := self._resolve_property():
+            return property_method
+
+        return self._resolve_legacy()
+
+    def _resolve_decorated(self) -> Callable | None:
+        """Find the most-derived @main decorated method in the MRO (method resolution order).
+
+        Returns:
+            Callable | None: The decorated main method, or None if not found.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+        """
+        classes_with_main = []
+        for base in self.cls.__mro__:
+            if base.__name__ == "Component" or base is ABC:
+                continue
+
+            main_method_name = next(
+                (name for name, method in base.__dict__.items() if callable(method) and hasattr(method, "__is_main__")),
+                None,
+            )
+
+            if main_method_name:
+                classes_with_main.append((base, main_method_name))
+
+        if not classes_with_main:
+            return None
+
+        most_derived_class, method_name = classes_with_main[0]
+        actual_method = getattr(self.cls, method_name)
+
+        self._validate_no_decorator_conflicts(classes_with_main, most_derived_class, actual_method)
+
+        return actual_method
+
+    def _validate_no_decorator_conflicts(
+        self, classes_with_main: list[tuple[type, str]], most_derived_class: type, actual_method: Callable
+    ) -> None:
+        """Validate that there are no conflicting @main decorators in multiple inheritance.
+
+        This method checks for conflicts only when multiple classes in the inheritance hierarchy have @main decorated
+        methods. It allows intentional overrides (when the most derived class defines its own @main method) but prevents
+        conflicts from multiple inheritance where different ancestors define different @main methods.
+
+        Args:
+            classes_with_main (list[tuple[type, str]]): List of (class, method_name) tuples for classes with @main.
+            most_derived_class (type): The most derived class in the hierarchy with @main.
+            actual_method (Callable): The resolved method from the most derived class.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors and the most derived class
+                is not the current class (indicating a true conflict rather than an intentional override).
+        """
+        if len(classes_with_main) > 1 and most_derived_class is not self.cls:
+            for _, name in classes_with_main[1:]:
+                other_method = getattr(self.cls, name)
+                if other_method is not actual_method:
+                    raise TypeError(
+                        f"Conflicting main methods inherited from multiple ancestors in {self.cls.__name__}. "
+                        "Please explicitly override with @main decorator."
+                    )
+
+    def _resolve_property(self) -> Callable | None:
+        """Find method via __main_method__ property.
+
+        Returns:
+            Callable | None: The method named by __main_method__, or None if not found.
+        """
+        if hasattr(self.cls, "__main_method__") and self.cls.__main_method__ is not None:
+            method_name = self.cls.__main_method__
+            return getattr(self.cls, method_name, None)
+
+    def _resolve_legacy(self) -> Callable | None:
+        """Fall back to _run method with deprecation warning.
+
+        Returns:
+            Callable | None: The _run method, or None if not found.
+        """
+        if hasattr(self.cls, "_run"):
+            self._logger.warning(
+                f"Using legacy _run method for {self.cls.__name__}. "
+                f"Consider using @main decorator to explicitly declare the main entrypoint.",
+                stacklevel=4,
+            )
+            return self.cls._run
+
+    def _warn_if_redundant_property(self) -> None:
+        """Emit warning if both @main decorator and __main_method__ are defined."""
+        if self.cls.__dict__.get("__main_method__") is not None:
+            self._logger.warning(
+                f"Both @main decorator and __main_method__ property are defined in {self.cls.__name__}. "
+                "The @main decorator takes precedence. This redundant configuration should be resolved.",
+                stacklevel=4,
+            )

gllm_core/utils/main_method_resolver.pyi

@@ -0,0 +1,54 @@
+from _typeshed import Incomplete
+from gllm_core.utils.logger_manager import LoggerManager as LoggerManager
+from typing import Callable
+
+class MainMethodResolver:
+    """Resolves the main entrypoint method for Component classes.
+
+    This resolver implements the precedence rules for determining which method
+    should be used as the main entrypoint:
+    1. Method decorated with @main in the most derived class.
+    2. Method named by __main_method__ property.
+    3. _run method (with deprecation warning).
+
+    Attributes:
+        cls (type): The Component class to resolve the main method for.
+    """
+    cls: Incomplete
+    def __init__(self, component_class: type) -> None:
+        """Initialize the resolver with a Component class.
+
+        Args:
+            component_class (type): The Component class to resolve the main method for.
+        """
+    @staticmethod
+    def validate_class(component_class: type) -> None:
+        """Validate main method configuration at class definition time.
+
+        This performs early validation that can be done when a Component subclass
+        is defined, before any instances are created or methods are called.
+
+        Validations performed:
+        1. Check that __main_method__ property points to an existing method
+        2. Check that only one @main decorator is used within the same class
+
+        Note: Multiple inheritance conflicts are intentionally NOT checked here,
+        as they are deferred to runtime (get_main()) to allow class definition
+        to succeed.
+
+        Args:
+            component_class (type): The Component class to validate.
+
+        Raises:
+            AttributeError: If __main_method__ refers to a non-existent method.
+            TypeError: If multiple methods are decorated with @main in the same class.
+        """
+    def resolve(self) -> Callable | None:
+        """Resolve the main method following precedence rules.
+
+        Returns:
+            Callable | None: The resolved main method, or None if not found.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+        """