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

chuk_tool_processor/models/tool_export_mixin.py

@@ -0,0 +1,29 @@
+# chuk_tool_processor/models/tool_export_mix_in.py
+from typing import Dict
+
+class ToolExportMixin:
+    """Mixin that lets any ValidatedTool advertise its schema."""
+
+    @classmethod
+    def to_openai(cls) -> Dict:
+        schema = cls.Arguments.model_json_schema()
+        return {
+            "type": "function",
+            "function": {
+                "name": cls.__name__.removesuffix("Tool").lower(),   # or keep explicit name
+                "description": (cls.__doc__ or "").strip(),
+                "parameters": schema,
+            },
+        }
+
+    @classmethod
+    def to_json_schema(cls) -> Dict:
+        return cls.Arguments.model_json_schema()
+
+    @classmethod
+    def to_xml(cls) -> str:
+        """Very small helper so existing XML-based parsers still work."""
+        name = cls.__name__.removesuffix("Tool").lower()
+        params = cls.Arguments.model_json_schema()["properties"]
+        args = ", ".join(params)
+        return f"<tool name=\"{name}\" args=\"{{{args}}}\"/>"

chuk_tool_processor/models/validated_tool.py

@@ -0,0 +1,155 @@
+# chuk_tool_processor/models/validated_tool.py
+"""
+Self-contained base-class for *declarative* tools.
+
+Subclass it like so:
+
+    class Add(ValidatedTool):
+        class Arguments(BaseModel):
+            x: int
+            y: int
+
+        class Result(BaseModel):
+            sum: int
+
+        def _execute(self, *, x: int, y: int) -> Result:
+            return self.Result(sum=x + y)
+"""
+from __future__ import annotations
+
+import html
+import inspect
+import json
+from typing import Any, Dict, TypeVar, Callable
+
+from pydantic import BaseModel, ValidationError
+
+from chuk_tool_processor.core.exceptions import ToolValidationError
+
+__all__ = [
+    "ValidatedTool",
+    "with_validation",
+]
+
+T_Validated = TypeVar("T_Validated", bound="ValidatedTool")
+
+
+# --------------------------------------------------------------------------- #
+# Helper mix-in – serialise a *class* into assorted formats
+# --------------------------------------------------------------------------- #
+class _ExportMixin:
+    """Static helpers that expose a tool class in other specs."""
+
+    # ------------------------------------------------------------------ #
+    # OpenAI Chat-Completions `tools=[…]`
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def to_openai(
+        cls: type[T_Validated],
+        *,
+        registry_name: str | None = None,
+    ) -> Dict[str, Any]:
+        """
+        Build the structure expected by `tools=[…]`.
+
+        Parameters
+        ----------
+        registry_name
+            When the registry has stored the tool under a *different* key
+            (e.g. ``"weather"`` vs class ``WeatherTool``) pass that key so
+            `function.name` and later look-ups line up.
+        """
+        fn_name = registry_name or cls.__name__
+        description = (cls.__doc__ or f"{fn_name} tool").strip()
+
+        return {
+            "type": "function",
+            "function": {
+                "name": fn_name,
+                "description": description,
+                "parameters": cls.Arguments.model_json_schema(),  # type: ignore[attr-defined]
+            },
+        }
+
+    # ------------------------------------------------------------------ #
+    # Plain JSON schema (arguments only)
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def to_json_schema(cls: type[T_Validated]) -> Dict[str, Any]:
+        return cls.Arguments.model_json_schema()  # type: ignore[attr-defined]
+
+    # ------------------------------------------------------------------ #
+    # Tiny XML tag – handy for unit-tests / demos
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def to_xml_tag(cls: type[T_Validated], **arguments: Any) -> str:
+        return (
+            f'<tool name="{html.escape(cls.__name__)}" '
+            f"args='{html.escape(json.dumps(arguments))}'/>"
+        )
+
+
+# --------------------------------------------------------------------------- #
+# The public validated base-class
+# --------------------------------------------------------------------------- #
+class ValidatedTool(_ExportMixin, BaseModel):
+    """Pydantic-validated base for new tools."""
+
+    # ------------------------------------------------------------------ #
+    # Inner models – override in subclasses
+    # ------------------------------------------------------------------ #
+    class Arguments(BaseModel):  # noqa: D401 – acts as a namespace
+        """Input model"""
+
+    class Result(BaseModel):  # noqa: D401
+        """Output model"""
+
+    # ------------------------------------------------------------------ #
+    # Public entry-point called by the processor
+    # ------------------------------------------------------------------ #
+    def execute(self: T_Validated, **kwargs: Any) -> BaseModel:
+        """Validate *kwargs*, run `_execute`, validate the result."""
+        try:
+            args = self.Arguments(**kwargs)  # type: ignore[arg-type]
+            res = self._execute(**args.model_dump())  # type: ignore[arg-type]
+
+            return (
+                res
+                if isinstance(res, self.Result)
+                else self.Result(**(res if isinstance(res, dict) else {"value": res}))
+            )
+        except ValidationError as exc:
+            raise ToolValidationError(self.__class__.__name__, exc.errors()) from exc
+
+    # ------------------------------------------------------------------ #
+    # Sub-classes must implement this
+    # ------------------------------------------------------------------ #
+    def _execute(self, **_kwargs: Any):  # noqa: D401 – expected override
+        raise NotImplementedError("Tool must implement _execute()")
+
+
+# --------------------------------------------------------------------------- #
+# Decorator to retrofit validation onto classic “imperative” tools
+# --------------------------------------------------------------------------- #
+def with_validation(cls):  # noqa: D401 – factory
+    """
+    Decorator that wraps an existing ``execute`` method with:
+
+    * argument validation (based on type hints)
+    * result validation (based on return annotation)
+    """
+    from chuk_tool_processor.utils.validation import (
+        validate_arguments,
+        validate_result,
+    )
+
+    original: Callable[..., Any] = cls.execute  # type: ignore[attr-defined]
+
+    def _wrapper(self, **kwargs):  # type: ignore[override]
+        tool_name = cls.__name__
+        validated = validate_arguments(tool_name, original, kwargs)
+        result = original(self, **validated)
+        return validate_result(tool_name, original, result)
+
+    cls.execute = _wrapper  # type: ignore[assignment]
+    return cls

chuk_tool_processor/plugins/discovery.py

@@ -1,205 +1,138 @@
 # chuk_tool_processor/plugins/discovery.py
+"""Plugin discovery & registry utilities for chuk_tool_processor"""
+from __future__ import annotations
+
 import importlib
 import inspect
-import pkgutil
-import sys
-from typing import Dict, List, Optional, Set, Type, Any
 import logging
+import pkgutil
+from typing import Any, Dict, List, Optional, Set, Type
 
 logger = logging.getLogger(__name__)
 
 
 class PluginRegistry:
-    """
-    Registry for discovered plugins.
-    """
-    def __init__(self):
+    """In‑memory registry keyed by *category → name*."""
+
+    def __init__(self) -> None:  # no side‑effects in import time
         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}")
-    
+        self._plugins.setdefault(category, {})[name] = plugin
+        logger.debug("Registered plugin %s.%s", 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.
-        """
+
+    def list_plugins(self, category: str | None = None) -> Dict[str, List[str]]:
         if category:
-            return {category: list(self._plugins.get(category, {}).keys())}
-        else:
-            return {cat: list(plugins.keys()) for cat, plugins in self._plugins.items()}
+            return {category: list(self._plugins.get(category, {}))}
+        return {cat: list(names) for cat, names 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.
-        """
+    """Recursively scans packages for plugin classes and registers them."""
+
+    def __init__(self, registry: PluginRegistry) -> None:
         self.registry = registry
-        self._discovered_modules: Set[str] = set()
-    
+        self._seen: Set[str] = set()
+
+        # optional parser subsystem
+        try:
+            from chuk_tool_processor.parsers.base import ParserPlugin as _PP  # noqa: WPS433
+        except ModuleNotFoundError:
+            _PP = None
+        self.ParserPlugin = _PP
+
+        # ExecutionStrategy always present inside core models
+        from chuk_tool_processor.models.execution_strategy import ExecutionStrategy  # noqa: WPS433
+
+        self.ExecutionStrategy = ExecutionStrategy
+
+    # ------------------------------------------------------------------
     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.
-        """
+        for pkg in package_paths:
+            self._walk(pkg)
+
+    # ------------------------------------------------------------------
+    def _walk(self, pkg_path: str) -> None:
         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.
-        """
+            pkg = importlib.import_module(pkg_path)
+        except ImportError as exc:  # pragma: no cover
+            logger.warning("Cannot import package %s: %s", pkg_path, exc)
+            return
+
+        for _, mod_name, is_pkg in pkgutil.iter_modules(pkg.__path__, pkg.__name__ + "."):
+            if mod_name in self._seen:
+                continue
+            self._seen.add(mod_name)
+            self._inspect_module(mod_name)
+            if is_pkg:
+                self._walk(mod_name)
+
+    # ------------------------------------------------------------------
+    def _inspect_module(self, mod_name: str) -> None:
         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__]:
+            module = importlib.import_module(mod_name)
+        except ImportError as exc:  # pragma: no cover
+            logger.warning("Cannot import module %s: %s", mod_name, exc)
+            return
+
+        for attr in module.__dict__.values():
+            if inspect.isclass(attr):
+                self._maybe_register(attr)
+
+    # ------------------------------------------------------------------
+    def _maybe_register(self, cls: Type) -> None:
+        """Register *cls* in all relevant plugin categories."""
+
+        # ---------------- parser plugins ------------------------------
+        looks_like_parser = callable(getattr(cls, "try_parse", None))
+        if looks_like_parser and not inspect.isabstract(cls):
+            # skip ABC base itself if available
+            if self.ParserPlugin and cls is self.ParserPlugin:
+                pass
+            else:
+                self.registry.register_plugin("parser", cls.__name__, cls())
+
+        # --------------- execution strategies -------------------------
+        if (
+            issubclass(cls, self.ExecutionStrategy)
+            and cls is not self.ExecutionStrategy
+            and not inspect.isabstract(cls)
+        ):
             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")
+
+        # --------------- explicit @plugin decorator -------------------
+        meta = getattr(cls, "_plugin_meta", None)
+        if meta and not inspect.isabstract(cls):
             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):
-                ...
-    """
+# ----------------------------------------------------------------------
+# public decorator helper
+# ----------------------------------------------------------------------
+
+def plugin(category: str, name: str | None = None):
+    """Decorator to mark a class as a plugin for explicit registration."""
+
     def decorator(cls):
-        cls._plugin_meta = {
-            "category": category,
-            "name": name or cls.__name__
-        }
+        cls._plugin_meta = {"category": category, "name": name or cls.__name__}
         return cls
+
     return decorator
 
 
-# Initialize the global plugin registry
+# ----------------------------------------------------------------------
+# Singletons & convenience wrappers
+# ----------------------------------------------------------------------
 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)
+def discover_default_plugins() -> None:
+    PluginDiscovery(plugin_registry).discover_plugins(["chuk_tool_processor.plugins"])
+
+
+def discover_plugins(package_paths: List[str]) -> None:
+    PluginDiscovery(plugin_registry).discover_plugins(package_paths)

chuk_tool_processor/plugins/parsers/__init__.py

@@ -1 +1 @@
-# chuk_tool_processor/plugins/parsers__init__.py
+# chuk_tool_processor/plugins/parsers/__init__.py

chuk_tool_processor/plugins/parsers/base.py

@@ -0,0 +1,18 @@
+# chuk_tool_processor/parsers/base.py
+from abc import ABC, abstractmethod
+from typing import List
+from chuk_tool_processor.models.tool_call import ToolCall
+
+
+class ParserPlugin(ABC):
+    """
+    Minimal interface every parser plug-in must implement.
+
+    The processor will feed the *raw text* (or dict) it receives from upstream
+    into `try_parse`.  If the plugin recognises the format it should return a
+    list of ToolCall objects; otherwise return an empty list.
+    """
+
+    @abstractmethod
+    def try_parse(self, raw: str) -> List[ToolCall]:
+        ...

chuk_tool_processor/plugins/parsers/function_call_tool_plugin.py

@@ -0,0 +1,81 @@
+# chuk_tool_processor/plugins/function_call_tool_plugin.py
+"""Function-call parser plugin.
+* Accepts dict **or** string input.
+* Coerces non-dict `arguments` to `{}` instead of rejecting.
+* Inherits from ``ParserPlugin`` so discovery categorises it as a *parser*.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List
+from pydantic import ValidationError
+
+# imports
+from .base import ParserPlugin
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.logging import get_logger
+
+# logger
+logger = get_logger("chuk_tool_processor.plugins.function_call_tool")
+
+# balanced‐brace JSON object regex – one level only (good enough for payloads)
+_JSON_OBJECT = re.compile(r"\{(?:[^{}]|(?:\{[^{}]*\}))*\}")
+
+
+class FunctionCallPlugin(ParserPlugin):
+    """Parse OpenAI-style **single** ``function_call`` objects."""
+
+    def try_parse(self, raw: str | Dict[str, Any]) -> List[ToolCall]:
+        payload: Dict[str, Any] | None
+        if isinstance(raw, dict):
+            payload = raw
+        else:
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError:
+                payload = None
+
+        calls: List[ToolCall] = []
+
+        # primary path -----------------------------------------------------
+        if isinstance(payload, dict):
+            calls.extend(self._extract_from_payload(payload))
+
+        # fallback – scan raw text for nested JSON blocks ------------------
+        if not calls and isinstance(raw, str):
+            for m in _JSON_OBJECT.finditer(raw):
+                try:
+                    sub = json.loads(m.group(0))
+                except json.JSONDecodeError:
+                    continue
+                calls.extend(self._extract_from_payload(sub))
+
+        return calls
+
+    # ------------------------------------------------------------------
+    def _extract_from_payload(self, payload: Dict[str, Any]) -> List[ToolCall]:
+        fc = payload.get("function_call")
+        if not isinstance(fc, dict):
+            return []
+
+        name = fc.get("name")
+        args = fc.get("arguments", {})
+
+        # arguments may be JSON‑encoded string or anything else
+        if isinstance(args, str):
+            try:
+                args = json.loads(args)
+            except json.JSONDecodeError:
+                args = {}
+        if not isinstance(args, dict):
+            args = {}
+
+        if not isinstance(name, str) or not name:
+            return []
+
+        try:
+            return [ToolCall(tool=name, arguments=args)]
+        except ValidationError:
+            logger.debug("Validation error while building ToolCall for %s", name)
+            return []

chuk_tool_processor/plugins/parsers/json_tool_plugin.py

@@ -0,0 +1,38 @@
+# chuk_tool_processor/parsers/json_tool.py
+"""JSON *tool_calls* parser plugin (drop-in).
+
+Accepts raw‐string or dict input where the top-level object includes a
+``tool_calls`` array – an early OpenAI Chat Completions schema.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, List
+from pydantic import ValidationError
+
+# imports
+from .base import ParserPlugin
+from chuk_tool_processor.models.tool_call import ToolCall
+
+class JsonToolPlugin(ParserPlugin):
+    """Extracts ``tool_calls`` array from a JSON response."""
+
+    def try_parse(self, raw: str | Any) -> List[ToolCall]:
+        try:
+            data = json.loads(raw) if isinstance(raw, str) else raw
+        except json.JSONDecodeError:
+            return []
+
+        if not isinstance(data, dict):
+            return []
+
+        calls = data.get("tool_calls", [])
+        out: List[ToolCall] = []
+
+        for c in calls:
+            try:
+                out.append(ToolCall(**c))
+            except ValidationError:
+                continue
+        return out
+