Native Integration¶

This section documents the native Python class integration capabilities of the ToolRegistry library.

Architecture Overview¶

The Native integration enables direct registration of Python class methods as tools within the ToolRegistry framework. This integration provides a seamless way to convert existing Python classes into callable tools:

Core Components¶

1. ClassToolIntegration: The main integration class that handles class method registration

2. Automatically detects static vs instance methods

3. Handles class instantiation when needed

4. Manages namespace assignment for organized tool hierarchy

5. Method Registration Logic: Intelligent registration that adapts to different class patterns

6. Static methods are registered directly from the class
7. Instance methods trigger automatic class instantiation
8. Mixed method types are handled with appropriate error messages

Design Philosophy¶

• Zero Configuration: Minimal setup required to register Python classes
• Intelligent Detection: Automatic detection of method types and instantiation needs
• Namespace Management: Automatic namespace generation based on class names
• Error Transparency: Clear error messages for common integration issues

Key Features¶

• Automatic Method Discovery: Scans classes for public callable methods
• Smart Instantiation: Handles both static and instance method registration
• Namespace Support: Automatic namespace generation from class names
• MRO Traversal: The traverse_mro parameter controls whether inherited methods from parent classes are included via Method Resolution Order traversal. When True (default), methods inherited from all parent classes (excluding object) are also included, with subclass methods taking priority. When False, only methods defined directly on the class are registered.
• Error Handling: Clear error messages for problematic class structures
• Async Support: Full compatibility with async/await patterns
• Reflection-Based: Uses Python's introspection capabilities for method discovery

Registration Patterns¶

Static Method Classes¶

class Calculator:
    @staticmethod
    def add(a: int, b: int) -> int:
        return a + b

Methods are registered directly without instantiation.

Instance Method Classes¶

class FileManager:
    def __init__(self, base_path: str):
        self.base_path = base_path

    def read_file(self, filename: str) -> str:
        # Implementation

Class is automatically instantiated and instance methods are registered.

Mixed Method Classes¶

class MixedClass:
    @staticmethod
    def static_method():
        pass

    def instance_method(self):
        pass

Automatically detected and handled appropriately.

Inherited Method Registration¶

By default (traverse_mro=True), methods inherited from parent classes are also registered:

class BaseTools:
    @staticmethod
    def base_method(x: int) -> int:
        return x * 2

class DerivedTools(BaseTools):
    @staticmethod
    def derived_method(x: int) -> int:
        return x * 3

# Default behavior (traverse_mro=True): both base_method and derived_method are registered
# With traverse_mro=False: only derived_method is registered

API Reference¶

ClassToolIntegration¶

Handles integration with Python classes for method registration.

ClassToolIntegration(registry: ToolRegistry, traverse_mro: bool = True)

register_class_methods(cls_or_instance: type | object, namespace: bool | str = False, constructor_kwargs: dict | None = None) -> None

register_class_methods_async(cls_or_instance: type | object, namespace: bool | str = False, constructor_kwargs: dict | None = None) -> None

Module Overview¶

Native Module¶

The main native integration module.

ClassToolIntegration(registry: ToolRegistry, traverse_mro: bool = True)

register_class_methods(cls_or_instance: type | object, namespace: bool | str = False, constructor_kwargs: dict | None = None) -> None

register_class_methods_async(cls_or_instance: type | object, namespace: bool | str = False, constructor_kwargs: dict | None = None) -> None

Native Utils¶

Utility functions for native integration.

get_all_static_methods(cls_or_instance: type | object, skip_list: list[str] | None = None, include_list: list[str] | None = None) -> list[str]

class Example:
    @staticmethod
    def static_method_one():
        pass

    @staticmethod
    def static_method_two():
        pass

get_all_static_methods(Example, skip_list=["static_method_two"])
# ['static_method_one']
get_all_static_methods(Example, include_list=["static_method_two", "static_method_three"])
# ['static_method_two']