chuk-tool-processor 0.1.0__py3-none-any.whl

chuk_tool_processor/plugins/discovery.py

@@ -0,0 +1,205 @@
+# chuk_tool_processor/plugins/discovery.py
+import importlib
+import inspect
+import pkgutil
+import sys
+from typing import Dict, List, Optional, Set, Type, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class PluginRegistry:
+    """
+    Registry for discovered plugins.
+    """
+    def __init__(self):
+        self._plugins: Dict[str, Dict[str, Any]] = {}
+    
+    def register_plugin(self, category: str, name: str, plugin: Any) -> None:
+        """
+        Register a plugin in the registry.
+        
+        Args:
+            category: Plugin category (e.g., "parser", "executor").
+            name: Plugin name.
+            plugin: Plugin implementation.
+        """
+        # Ensure category exists
+        if category not in self._plugins:
+            self._plugins[category] = {}
+            
+        # Register plugin
+        self._plugins[category][name] = plugin
+        logger.debug(f"Registered plugin: {category}.{name}")
+    
+    def get_plugin(self, category: str, name: str) -> Optional[Any]:
+        """
+        Get a plugin from the registry.
+        
+        Args:
+            category: Plugin category.
+            name: Plugin name.
+            
+        Returns:
+            Plugin implementation or None if not found.
+        """
+        return self._plugins.get(category, {}).get(name)
+    
+    def list_plugins(self, category: Optional[str] = None) -> Dict[str, List[str]]:
+        """
+        List registered plugins.
+        
+        Args:
+            category: Optional category filter.
+            
+        Returns:
+            Dict mapping categories to lists of plugin names.
+        """
+        if category:
+            return {category: list(self._plugins.get(category, {}).keys())}
+        else:
+            return {cat: list(plugins.keys()) for cat, plugins in self._plugins.items()}
+
+
+class PluginDiscovery:
+    """
+    Discovers and loads plugins from specified packages.
+    """
+    def __init__(self, registry: PluginRegistry):
+        """
+        Initialize the plugin discovery.
+        
+        Args:
+            registry: Plugin registry to register discovered plugins.
+        """
+        self.registry = registry
+        self._discovered_modules: Set[str] = set()
+    
+    def discover_plugins(self, package_paths: List[str]) -> None:
+        """
+        Discover plugins in the specified packages.
+        
+        Args:
+            package_paths: List of package paths to search for plugins.
+        """
+        for package_path in package_paths:
+            self._discover_in_package(package_path)
+    
+    def _discover_in_package(self, package_path: str) -> None:
+        """
+        Discover plugins in a single package.
+        
+        Args:
+            package_path: Package path to search.
+        """
+        try:
+            # Import the package
+            package = importlib.import_module(package_path)
+            
+            # Walk through package modules
+            for _, name, is_pkg in pkgutil.iter_modules(package.__path__, package.__name__ + "."):
+                # Skip if already processed
+                if name in self._discovered_modules:
+                    continue
+                    
+                self._discovered_modules.add(name)
+                
+                # Process module
+                self._process_module(name)
+                
+                # Recurse into subpackages
+                if is_pkg:
+                    self._discover_in_package(name)
+                    
+        except ImportError as e:
+            logger.warning(f"Failed to import package {package_path}: {e}")
+    
+    def _process_module(self, module_name: str) -> None:
+        """
+        Process a module for plugins.
+        
+        Args:
+            module_name: Module name to process.
+        """
+        try:
+            # Import the module
+            module = importlib.import_module(module_name)
+            
+            # Find all classes in the module
+            for attr_name in dir(module):
+                attr = getattr(module, attr_name)
+                
+                # Skip non-classes
+                if not inspect.isclass(attr):
+                    continue
+                
+                # Check if it's a plugin
+                self._register_if_plugin(attr)
+                
+        except ImportError as e:
+            logger.warning(f"Failed to import module {module_name}: {e}")
+    
+    def _register_if_plugin(self, cls: Type) -> None:
+        """
+        Register a class if it's a plugin.
+        
+        Args:
+            cls: Class to check.
+        """
+        # Check if it's a parser plugin
+        if hasattr(cls, "try_parse") and callable(getattr(cls, "try_parse")):
+            self.registry.register_plugin("parser", cls.__name__, cls())
+        
+        # Check if it's an execution strategy
+        if "ExecutionStrategy" in [base.__name__ for base in cls.__mro__]:
+            self.registry.register_plugin("execution_strategy", cls.__name__, cls)
+        
+        # Check if it has plugin metadata
+        if hasattr(cls, "_plugin_meta"):
+            meta = getattr(cls, "_plugin_meta")
+            self.registry.register_plugin(meta.get("category", "unknown"), meta.get("name", cls.__name__), cls())
+
+
+def plugin(category: str, name: Optional[str] = None):
+    """
+    Decorator to mark a class as a plugin.
+    
+    Example:
+        @plugin(category="parser", name="custom_format")
+        class CustomFormatParser:
+            def try_parse(self, raw: str):
+                ...
+    """
+    def decorator(cls):
+        cls._plugin_meta = {
+            "category": category,
+            "name": name or cls.__name__
+        }
+        return cls
+    return decorator
+
+
+# Initialize the global plugin registry
+plugin_registry = PluginRegistry()
+
+
+# Function to discover plugins in the default package
+def discover_default_plugins():
+    """
+    Discover plugins in the default package.
+    """
+    discovery = PluginDiscovery(plugin_registry)
+    discovery.discover_plugins(["chuk_tool_processor.plugins"])
+
+
+# Function to discover plugins in custom packages
+def discover_plugins(package_paths: List[str]):
+    """
+    Discover plugins in custom packages.
+    
+    Args:
+        package_paths: List of package paths to search for plugins.
+    """
+    discovery = PluginDiscovery(plugin_registry)
+    discovery.discover_plugins(package_paths)

chuk_tool_processor/plugins/parsers/__init__.py

@@ -0,0 +1 @@
+# chuk_tool_processor/plugins/parsers__init__.py

chuk_tool_processor/plugins/parsers/function_call_tool.py

@@ -0,0 +1,105 @@
+# chuk_tool_processor/plugins/function_call_tool.py
+import json
+import re
+from typing import List, Any, Dict
+from pydantic import ValidationError
+
+# imports
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.utils.logging import get_logger
+
+# logger
+logger = get_logger("chuk_tool_processor.plugins.function_call_tool")
+
+class FunctionCallPlugin:
+    """
+    Parse OpenAI-style `function_call` payloads embedded in the LLM response.
+    
+    Supports two formats:
+    1. JSON object with function_call field:
+      {
+        "function_call": {
+          "name": "my_tool",
+          "arguments": '{"x":1,"y":"two"}'
+        }
+      }
+      
+    2. JSON object with function_call field and already parsed arguments:
+      {
+        "function_call": {
+          "name": "my_tool",
+          "arguments": {"x":1, "y":"two"}
+        }
+      }
+    """
+    def try_parse(self, raw: str) -> List[ToolCall]:
+        calls: List[ToolCall] = []
+        
+        # First, try to parse as a complete JSON object
+        try:
+            payload = json.loads(raw)
+            
+            # Check if this is a function call payload
+            if isinstance(payload, dict) and "function_call" in payload:
+                fc = payload.get("function_call")
+                if not isinstance(fc, dict):
+                    return []
+                
+                name = fc.get("name")
+                args = fc.get("arguments", {})
+                
+                # Arguments sometimes come back as a JSON-encoded string
+                if isinstance(args, str):
+                    try:
+                        args = json.loads(args)
+                    except json.JSONDecodeError:
+                        # Leave as empty dict if malformed but still create the call
+                        args = {}
+                
+                # Only proceed if we have a valid name
+                if not isinstance(name, str) or not name:
+                    return []
+                
+                try:
+                    call = ToolCall(tool=name, arguments=args if isinstance(args, Dict) else {})
+                    calls.append(call)
+                    logger.debug(f"Found function call to {name}")
+                except ValidationError:
+                    # invalid tool name or args shape
+                    logger.warning(f"Invalid function call: {name}")
+            
+            # Look for nested function calls
+            if not calls:
+                # Try to find function calls in nested objects
+                json_str = json.dumps(payload)
+                json_pattern = r'\{(?:[^{}]|(?:\{[^{}]*\}))*\}'
+                matches = re.finditer(json_pattern, json_str)
+                
+                for match in matches:
+                    # Skip if it's the complete string we already parsed
+                    json_substr = match.group(0)
+                    if json_substr == json_str:
+                        continue
+                        
+                    try:
+                        nested_payload = json.loads(json_substr)
+                        if isinstance(nested_payload, dict) and "function_call" in nested_payload:
+                            nested_calls = self.try_parse(json_substr)
+                            calls.extend(nested_calls)
+                    except json.JSONDecodeError:
+                        continue
+                
+        except json.JSONDecodeError:
+            # If it's not valid JSON, try to extract function calls using regex
+            json_pattern = r'\{(?:[^{}]|(?:\{[^{}]*\}))*\}'
+            matches = re.finditer(json_pattern, raw)
+            
+            for match in matches:
+                json_str = match.group(0)
+                try:
+                    nested_calls = self.try_parse(json_str)
+                    calls.extend(nested_calls)
+                except Exception:
+                    continue
+        
+        return calls

chuk_tool_processor/plugins/parsers/json_tool.py

@@ -0,0 +1,17 @@
+# chuk_tool_processor/plugins/json_tool.py
+import json
+from typing import List
+from pydantic import ValidationError
+
+# tool processor
+from chuk_tool_processor.models.tool_call import ToolCall
+
+class JsonToolPlugin:
+    """Parse JSON-encoded `tool_calls` field."""
+    def try_parse(self, raw: str) -> List[ToolCall]:
+        try:
+            data = json.loads(raw)
+            calls = data.get('tool_calls', []) if isinstance(data, dict) else []
+            return [ToolCall(**c) for c in calls]
+        except (json.JSONDecodeError, ValidationError):
+            return []

chuk_tool_processor/plugins/parsers/xml_tool.py

@@ -0,0 +1,41 @@
+# chuk_tool_processor/plugins/xml_tool.py
+import re
+import json
+from typing import List
+from pydantic import ValidationError
+
+# tool processor
+from chuk_tool_processor.models.tool_call import ToolCall
+
+class XmlToolPlugin:
+    """
+    Parse XML-like `<tool name="..." args='{"x":1}'/>` constructs,
+    supporting both single- and double-quoted attributes.
+    """
+    _pattern = re.compile(
+        r'<tool\s+'
+        r'name=(?P<q1>["\'])(?P<tool>.+?)(?P=q1)\s+'
+        r'args=(?P<q2>["\'])(?P<args>.*?)(?P=q2)\s*/>'
+    )
+
+    def try_parse(self, raw: str) -> List[ToolCall]:
+        calls: List[ToolCall] = []
+        for m in self._pattern.finditer(raw):
+            tool_name = m.group('tool')
+            raw_args = m.group('args')
+            # Decode the JSON payload in the args attribute
+            try:
+                args = json.loads(raw_args) if raw_args else {}
+            except (json.JSONDecodeError, ValidationError):
+                args = {}
+
+            # Validate & construct the ToolCall
+            try:
+                call = ToolCall(tool=tool_name, arguments=args)
+                calls.append(call)
+            except ValidationError:
+                # Skip malformed calls
+                continue
+
+        return calls
+

chuk_tool_processor/registry/__init__.py

@@ -0,0 +1,20 @@
+"""
+Tool registry package for managing and accessing tool implementations.
+"""
+from chuk_tool_processor.registry.interface import ToolRegistryInterface
+from chuk_tool_processor.registry.metadata import ToolMetadata
+from chuk_tool_processor.registry.provider import ToolRegistryProvider
+from chuk_tool_processor.registry.decorators import register_tool
+from chuk_tool_processor.registry.provider import get_registry
+
+# Create and expose the default registry
+default_registry = get_registry()
+
+__all__ = [
+    'ToolRegistryInterface',
+    'ToolMetadata',
+    'ToolRegistryProvider',
+    'register_tool',
+    'default_registry',
+    'get_registry',
+]

chuk_tool_processor/registry/decorators.py

@@ -0,0 +1,42 @@
+# chuk_tool_processor/registry/decorators.py
+"""
+Decorators for registering tools with the registry.
+"""
+
+from functools import wraps
+from typing import Any, Callable, Dict, Optional, Type, TypeVar
+
+from chuk_tool_processor.registry.provider import ToolRegistryProvider
+
+T = TypeVar('T')
+
+
+def register_tool(name: Optional[str] = None, namespace: str = "default", **metadata):
+    """
+    Decorator for registering tools with the global registry.
+    
+    Example:
+        @register_tool(name="my_tool", namespace="math", description="Performs math operations")
+        class MyTool:
+            def execute(self, x: int, y: int) -> int:
+                return x + y
+    
+    Args:
+        name: Optional explicit name; if omitted, uses class.__name__.
+        namespace: Namespace for the tool (default: "default").
+        **metadata: Additional metadata for the tool.
+    
+    Returns:
+        A decorator function that registers the class with the registry.
+    """
+    def decorator(cls: Type[T]) -> Type[T]:
+        registry = ToolRegistryProvider.get_registry()
+        registry.register_tool(cls, name=name, namespace=namespace, metadata=metadata)
+        
+        @wraps(cls)
+        def wrapper(*args: Any, **kwargs: Dict[str, Any]) -> T:
+            return cls(*args, **kwargs)
+        
+        return wrapper
+    
+    return decorator

chuk_tool_processor/registry/interface.py

@@ -0,0 +1,79 @@
+# chuk_tool_processor/registry/interface.py
+"""
+Defines the interface for tool registries.
+"""
+from typing import Protocol, Any, Dict, List, Optional, Tuple
+
+# imports
+from chuk_tool_processor.registry.metadata import ToolMetadata
+
+
+class ToolRegistryInterface(Protocol):
+    """
+    Protocol for a tool registry. Implementations should allow registering tools
+    and retrieving them by name and namespace.
+    """
+    def register_tool(
+        self, 
+        tool: Any, 
+        name: Optional[str] = None,
+        namespace: str = "default",
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> None:
+        """
+        Register a tool implementation.
+
+        Args:
+            tool: The tool class or instance with an `execute` method.
+            name: Optional explicit name; if omitted, uses tool.__name__.
+            namespace: Namespace for the tool (default: "default").
+            metadata: Optional additional metadata for the tool.
+        """
+        ...
+
+    def get_tool(self, name: str, namespace: str = "default") -> Optional[Any]:
+        """
+        Retrieve a registered tool by name and namespace.
+        
+        Args:
+            name: The name of the tool.
+            namespace: The namespace of the tool (default: "default").
+            
+        Returns:
+            The tool implementation or None if not found.
+        """
+        ...
+
+    def get_metadata(self, name: str, namespace: str = "default") -> Optional[ToolMetadata]:
+        """
+        Retrieve metadata for a registered tool.
+        
+        Args:
+            name: The name of the tool.
+            namespace: The namespace of the tool (default: "default").
+            
+        Returns:
+            ToolMetadata if found, None otherwise.
+        """
+        ...
+
+    def list_tools(self, namespace: Optional[str] = None) -> List[Tuple[str, str]]:
+        """
+        List all registered tool names, optionally filtered by namespace.
+        
+        Args:
+            namespace: Optional namespace filter.
+            
+        Returns:
+            List of (namespace, name) tuples.
+        """
+        ...
+
+    def list_namespaces(self) -> List[str]:
+        """
+        List all registered namespaces.
+        
+        Returns:
+            List of namespace names.
+        """
+        ...

chuk_tool_processor/registry/metadata.py

@@ -0,0 +1,36 @@
+# chuk_tool_processor/registry/metadata.py
+"""
+Tool metadata models for the registry.
+"""
+from typing import Any, Dict, Optional, Set
+from pydantic import BaseModel, Field
+
+
+class ToolMetadata(BaseModel):
+    """
+    Metadata for registered tools.
+    
+    Attributes:
+        name: The name of the tool.
+        namespace: The namespace the tool belongs to.
+        description: Optional description of the tool's functionality.
+        version: Version of the tool implementation.
+        is_async: Whether the tool's execute method is asynchronous.
+        argument_schema: Optional schema for the tool's arguments.
+        result_schema: Optional schema for the tool's result.
+        requires_auth: Whether the tool requires authentication.
+        tags: Set of tags associated with the tool.
+    """
+    name: str = Field(..., description="Tool name")
+    namespace: str = Field("default", description="Namespace the tool belongs to")
+    description: Optional[str] = Field(None, description="Tool description")
+    version: str = Field("1.0.0", description="Tool implementation version")
+    is_async: bool = Field(False, description="Whether the tool's execute method is asynchronous")
+    argument_schema: Optional[Dict[str, Any]] = Field(None, description="Schema for the tool's arguments")
+    result_schema: Optional[Dict[str, Any]] = Field(None, description="Schema for the tool's result")
+    requires_auth: bool = Field(False, description="Whether the tool requires authentication")
+    tags: Set[str] = Field(default_factory=set, description="Tags associated with the tool")
+
+    def __str__(self) -> str:
+        """String representation of the tool metadata."""
+        return f"{self.namespace}.{self.name} (v{self.version})"

chuk_tool_processor/registry/provider.py

@@ -0,0 +1,44 @@
+# chuk_tool_processor/registry/provider.py
+"""
+Registry provider that maintains a global tool registry.
+"""
+from typing import Optional
+
+# imports
+from chuk_tool_processor.registry.interface import ToolRegistryInterface
+from chuk_tool_processor.registry.providers import get_registry
+
+
+class ToolRegistryProvider:
+    """
+    Global provider for a ToolRegistryInterface implementation.
+    Use `set_registry` to override (e.g., for testing).
+    
+    This class provides a singleton-like access to a registry implementation,
+    allowing components throughout the application to access the same registry
+    without having to pass it explicitly.
+    """
+    # Initialize with default registry
+    _registry: Optional[ToolRegistryInterface] = None
+
+    @classmethod
+    def get_registry(cls) -> ToolRegistryInterface:
+        """
+        Get the current registry instance.
+        
+        Returns:
+            The current registry instance.
+        """
+        if cls._registry is None:
+            cls._registry = get_registry()
+        return cls._registry
+
+    @classmethod
+    def set_registry(cls, registry: ToolRegistryInterface) -> None:
+        """
+        Set the global registry instance.
+        
+        Args:
+            registry: The registry instance to use.
+        """
+        cls._registry = registry

chuk_tool_processor/registry/providers/__init__.py

@@ -0,0 +1,41 @@
+"""
+Registry provider implementations and factory functions.
+"""
+
+import os
+from typing import Optional
+
+from chuk_tool_processor.registry.interface import ToolRegistryInterface
+from chuk_tool_processor.registry.providers.memory import InMemoryToolRegistry
+
+
+def get_registry(
+    provider_type: Optional[str] = None, 
+    **kwargs
+) -> ToolRegistryInterface:
+    """
+    Factory function to get a registry implementation.
+    
+    Args:
+        provider_type: Type of registry provider to use. Options:
+            - "memory" (default): In-memory implementation
+            - "redis": Redis-backed implementation (if available)
+            - "sqlalchemy": Database-backed implementation (if available)
+        **kwargs: Additional configuration for the provider.
+    
+    Returns:
+        A registry implementation.
+    
+    Raises:
+        ImportError: If the requested provider is not available.
+        ValueError: If the provider type is not recognized.
+    """
+    # Use environment variable if not specified
+    if provider_type is None:
+        provider_type = os.environ.get("CHUK_TOOL_REGISTRY_PROVIDER", "memory")
+    
+    # Create the appropriate provider
+    if provider_type == "memory":
+        return InMemoryToolRegistry()
+    else:
+        raise ValueError(f"Unknown registry provider type: {provider_type}")