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

chuk_tool_processor/plugins/parsers/openai_tool_plugin.py

@@ -0,0 +1,76 @@
+# chuk_tool_processor/parsers/openai_tool_plugin.py
+"""
+Parser for OpenAI Chat-Completions responses that contain a `tool_calls` array.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, List
+
+from pydantic import ValidationError
+
+from .base import ParserPlugin
+from chuk_tool_processor.models.tool_call import ToolCall
+
+
+class OpenAIToolPlugin(ParserPlugin):
+    """
+    Understands responses that look like:
+
+    {
+        "tool_calls": [
+            {
+                "id": "call_abc",
+                "type": "function",
+                "function": {
+                    "name": "weather",
+                    "arguments": "{\"location\": \"New York\"}"
+                }
+            },
+            …
+        ]
+    }
+    """
+
+    def try_parse(self, raw: str | Any) -> List[ToolCall]:
+        # ------------------------------------------------------------------ #
+        # Parse the incoming JSON (string or already-dict)
+        # ------------------------------------------------------------------ #
+        try:
+            data = json.loads(raw) if isinstance(raw, str) else raw
+        except (TypeError, json.JSONDecodeError):
+            return []
+
+        if not isinstance(data, dict) or "tool_calls" not in data:
+            return []
+
+        # ------------------------------------------------------------------ #
+        # Convert each entry into a ToolCall
+        # ------------------------------------------------------------------ #
+        calls: List[ToolCall] = []
+        for tc in data["tool_calls"]:
+            fn = tc.get("function", {})
+            name = fn.get("name")
+            args = fn.get("arguments", {})
+
+            if not isinstance(name, str) or not name:
+                continue
+
+            # arguments come back as a JSON-encoded string – decode if needed
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except json.JSONDecodeError:
+                    args = {}
+
+            if not isinstance(args, dict):
+                args = {}
+
+            try:
+                # `tool` must match the **registry key** (e.g. "weather")
+                calls.append(ToolCall(tool=name, arguments=args))
+            except ValidationError:
+                continue  # skip malformed entries
+
+        return calls

chuk_tool_processor/plugins/parsers/xml_tool.py

@@ -1,41 +1,45 @@
 # chuk_tool_processor/plugins/xml_tool.py
-import re
+"""XML tool-call parser plugin.
+Understands `<tool name="..." args='{"x":1}'/>` single-line constructs –
+format used by many examples and test-fixtures.
+"""
+from __future__ import annotations
+
 import json
+import re
 from typing import List
 from pydantic import ValidationError
 
-# tool processor
+# imports
+from .base import ParserPlugin
 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*/>'
+
+
+class XmlToolPlugin(ParserPlugin):
+    """Parse XML-like tool-call tags."""
+
+    _TAG = 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]:
+    def try_parse(self, raw):  # type: ignore[override]
+        if not isinstance(raw, str):  # XML form only exists in strings
+            return []
+
         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
+        for m in self._TAG.finditer(raw):
+            tool_name = m.group("tool")
+            raw_args = m.group("args")
             try:
                 args = json.loads(raw_args) if raw_args else {}
-            except (json.JSONDecodeError, ValidationError):
+            except json.JSONDecodeError:
                 args = {}
 
-            # Validate & construct the ToolCall
             try:
-                call = ToolCall(tool=tool_name, arguments=args)
-                calls.append(call)
+                calls.append(ToolCall(tool=tool_name, arguments=args))
             except ValidationError:
-                # Skip malformed calls
-                continue
-
+                continue  # skip malformed
         return calls
-

chuk_tool_processor/registry/__init__.py

@@ -1,20 +1,21 @@
 """
 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()
+# --------------------------------------------------------------------------- #
+# Expose the *singleton* registry that every part of the library should use
+# --------------------------------------------------------------------------- #
+default_registry = ToolRegistryProvider.get_registry()
 
 __all__ = [
-    'ToolRegistryInterface',
-    'ToolMetadata',
-    'ToolRegistryProvider',
-    'register_tool',
-    'default_registry',
-    'get_registry',
-]
+    "ToolRegistryInterface",
+    "ToolMetadata",
+    "ToolRegistryProvider",
+    "register_tool",
+    "default_registry",
+]

chuk_tool_processor/registry/auto_register.py

@@ -0,0 +1,125 @@
+# chuk_tool_processor/registry/auto_register.py
+"""
+Tiny “auto-register” helpers so you can do
+
+    register_fn_tool(my_function)
+    register_langchain_tool(my_langchain_tool)
+
+and they immediately show up in the global registry.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import types
+from typing import Callable, ForwardRef, Type, get_type_hints
+
+import anyio
+from pydantic import BaseModel, create_model
+
+try:  # optional dependency
+    from langchain.tools.base import BaseTool  # type: ignore
+except ModuleNotFoundError:  # pragma: no cover
+    BaseTool = None  # noqa: N816  – keep the name for isinstance() checks
+
+from chuk_tool_processor.registry.decorators import register_tool
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# internals – build a Pydantic schema from an arbitrary callable
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def _auto_schema(func: Callable) -> Type[BaseModel]:
+    """
+    Turn a function signature into a `pydantic.BaseModel` subclass.
+
+    *Unknown* or *un-imported* annotations (common with third-party libs that
+    use forward-refs without importing the target – e.g. ``uuid.UUID`` in
+    LangChain’s `CallbackManagerForToolRun`) default to ``str`` instead of
+    crashing `get_type_hints()`.
+    """
+    try:
+        hints = get_type_hints(func)
+    except Exception:
+        hints = {}
+
+    fields: dict[str, tuple[type, object]] = {}
+    for param in inspect.signature(func).parameters.values():
+        raw_hint = hints.get(param.name, param.annotation)
+        # Default to ``str`` for ForwardRef / string annotations or if we
+        # couldn’t resolve the type.
+        hint: type = (
+            raw_hint
+            if raw_hint not in (inspect._empty, None, str)
+            and not isinstance(raw_hint, (str, ForwardRef))
+            else str
+        )
+        fields[param.name] = (hint, ...)  # “...”  → required
+
+    return create_model(f"{func.__name__.title()}Args", **fields)  # type: ignore
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# 1️⃣  plain Python function  (sync **or** async)
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def register_fn_tool(
+    func: Callable,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> None:
+    """Register a plain function as a tool – one line is all you need."""
+
+    schema = _auto_schema(func)
+    name = name or func.__name__
+    description = (description or func.__doc__ or "").strip()
+
+    @register_tool(name=name, description=description, arg_schema=schema)
+    class _Tool:  # noqa: D401, N801 – internal auto-wrapper
+        async def _execute(self, **kwargs):
+            if inspect.iscoroutinefunction(func):
+                return await func(**kwargs)
+            # off-load blocking sync work
+            return await anyio.to_thread.run_sync(func, **kwargs)
+
+
+# ────────────────────────────────────────────────────────────────────────────
+# 2️⃣  LangChain BaseTool (or anything that quacks like it)
+# ────────────────────────────────────────────────────────────────────────────
+
+
+def register_langchain_tool(
+    tool,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> None:
+    """
+    Register a **LangChain** `BaseTool` instance (or anything exposing
+    ``.run`` / ``.arun``).
+
+    If LangChain isn’t installed you’ll get a clear error instead of an import
+    failure deep in the stack.
+    """
+    if BaseTool is None:
+        raise RuntimeError(
+            "register_langchain_tool() requires LangChain - "
+            "install with `pip install langchain`"
+        )
+
+    if not isinstance(tool, BaseTool):  # pragma: no cover
+        raise TypeError(
+            "Expected a langchain.tools.base.BaseTool instance – got "
+            f"{type(tool).__name__}"
+        )
+
+    fn = tool.arun if hasattr(tool, "arun") else tool.run  # prefer async
+    register_fn_tool(
+        fn,
+        name=name or tool.name or tool.__class__.__name__,
+        description=description or tool.description or (tool.__doc__ or ""),
+    )

chuk_tool_processor/registry/provider.py

@@ -1,44 +1,99 @@
-# chuk_tool_processor/registry/provider.py
 """
-Registry provider that maintains a global tool registry.
+Global access to *the* tool registry instance.
+
+There are two public faces:
+
+1.  **Module helpers**  
+    • `get_registry()` lazily instantiates a default `InMemoryToolRegistry`
+      and memoises it in the module-level variable ``_REGISTRY``.  
+    • `set_registry()` lets callers replace or reset that singleton.
+
+2.  **`ToolRegistryProvider` shim**  
+    Earlier versions exposed a static wrapper.  Tests rely on being able to
+    monkey-patch the *module-level* factory and to clear the cached instance
+    by setting `ToolRegistryProvider._registry = None`.  We therefore keep a
+    **separate class-level cache** (`_registry`) and call the *current*
+    module-level `get_registry()` **only when the cache is empty**.
+
+The contract verified by the test-suite is:
+
+* The module-level factory is invoked **exactly once** per fresh cache.
+* `ToolRegistryProvider.set_registry(obj)` overrides subsequent retrievals.
+* `ToolRegistryProvider.set_registry(None)` resets the cache so the next
+  `get_registry()` call invokes (and honours any monkey-patched) factory.
 """
+from __future__ import annotations
+
 from typing import Optional
 
-# imports
-from chuk_tool_processor.registry.interface import ToolRegistryInterface
-from chuk_tool_processor.registry.providers import get_registry
+from .interface import ToolRegistryInterface
+from .providers.memory import InMemoryToolRegistry
+
+# --------------------------------------------------------------------------- #
+# Module-level singleton used by the helper functions
+# --------------------------------------------------------------------------- #
+_REGISTRY: Optional[ToolRegistryInterface] = None
+# --------------------------------------------------------------------------- #
+
 
+def _default_registry() -> ToolRegistryInterface:
+    """Create the default in-memory registry."""
+    return InMemoryToolRegistry()
 
-class ToolRegistryProvider:
+
+def get_registry() -> ToolRegistryInterface:
     """
-    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.
+    Return the process-wide registry, creating it on first use.
+
+    This function *may* be monkey-patched in tests; call it via
+    ``globals()["get_registry"]()`` if you need the latest binding.
     """
-    # Initialize with default registry
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = _default_registry()
+    return _REGISTRY
+
+
+def set_registry(registry: ToolRegistryInterface | None) -> None:
+    """
+    Replace or clear the global registry.
+
+    Passing ``None`` resets the singleton so that the next `get_registry()`
+    call recreates it (useful in tests).
+    """
+    global _REGISTRY
+    _REGISTRY = registry
+
+
+# --------------------------------------------------------------------------- #
+# Back-compat shim used by legacy import paths and the test-suite
+# --------------------------------------------------------------------------- #
+class ToolRegistryProvider:                       # noqa: D401
+    """Legacy static wrapper retaining historical semantics."""
+
+    # The test-suite directly mutates this attribute, so we keep it.
     _registry: Optional[ToolRegistryInterface] = None
 
-    @classmethod
-    def get_registry(cls) -> ToolRegistryInterface:
+    # ------------------------ public API ------------------------ #
+    @staticmethod
+    def get_registry() -> ToolRegistryInterface:
         """
-        Get the current registry instance.
-        
-        Returns:
-            The current registry instance.
+        Return the cached instance or, if absent, call the *current*
+        module-level `get_registry()` exactly once to populate it.
         """
-        if cls._registry is None:
-            cls._registry = get_registry()
-        return cls._registry
+        if ToolRegistryProvider._registry is None:
+            # Honour any runtime monkey-patching of the factory.
+            ToolRegistryProvider._registry = globals()["get_registry"]()
+        return ToolRegistryProvider._registry
 
-    @classmethod
-    def set_registry(cls, registry: ToolRegistryInterface) -> None:
+    @staticmethod
+    def set_registry(registry: ToolRegistryInterface | None) -> None:
         """
-        Set the global registry instance.
-        
-        Args:
-            registry: The registry instance to use.
+        Override the cached registry.
+
+        *   If ``registry`` is an object, all subsequent `get_registry()`
+            calls return it without touching the factory.
+        *   If ``registry`` is ``None``, the cache is cleared so the next
+            `get_registry()` call invokes the (possibly patched) factory.
         """
-        cls._registry = registry
+        ToolRegistryProvider._registry = registry

chuk_tool_processor/registry/providers/memory.py

@@ -1,8 +1,11 @@
 # chuk_tool_processor/registry/providers/memory.py
+# chuk_tool_processor/registry/providers/memory.py
 """
 In-memory implementation of the tool registry.
 """
 
+from __future__ import annotations
+
 import inspect
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -14,152 +17,114 @@ from chuk_tool_processor.registry.metadata import ToolMetadata
 class InMemoryToolRegistry(ToolRegistryInterface):
     """
     In-memory implementation of ToolRegistryInterface with namespace support.
-    
-    This implementation stores tools and their metadata in memory,
-    organized by namespace. It's suitable for single-process applications
-    or for testing, but doesn't provide persistence or sharing across
-    multiple processes.
+
+    Suitable for single-process apps or tests; not persisted across processes.
     """
-    def __init__(self):
-        """Initialize the in-memory registry."""
-        # Store tools as {namespace: {name: tool}}
+
+    # ------------------------------------------------------------------ #
+    # construction
+    # ------------------------------------------------------------------ #
+
+    def __init__(self) -> None:
+        # {namespace: {tool_name: tool_obj}}
         self._tools: Dict[str, Dict[str, Any]] = {}
-        # Store metadata as {namespace: {name: metadata}}
+        # {namespace: {tool_name: ToolMetadata}}
         self._metadata: Dict[str, Dict[str, ToolMetadata]] = {}
 
+    # ------------------------------------------------------------------ #
+    # registration
+    # ------------------------------------------------------------------ #
+
     def register_tool(
-        self, 
-        tool: Any, 
+        self,
+        tool: Any,
         name: Optional[str] = None,
         namespace: str = "default",
-        metadata: Optional[Dict[str, Any]] = None
+        metadata: Optional[Dict[str, Any]] = None,
     ) -> None:
-        """
-        Register a tool implementation.
+        # ensure namespace buckets
+        self._tools.setdefault(namespace, {})
+        self._metadata.setdefault(namespace, {})
 
-        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.
-        """
-        # Ensure the namespace exists
-        if namespace not in self._tools:
-            self._tools[namespace] = {}
-            self._metadata[namespace] = {}
-            
-        # Determine tool name
         key = name or getattr(tool, "__name__", None) or repr(tool)
-        
-        # Register the tool
         self._tools[namespace][key] = tool
-        
-        # Create and store metadata
+
+        # build metadata -------------------------------------------------
         is_async = inspect.iscoroutinefunction(getattr(tool, "execute", None))
-        
-        # Get description from docstring if available
-        description = None
-        if hasattr(tool, "__doc__") and tool.__doc__:
-            description = inspect.getdoc(tool)
-        
-        # Create metadata object
-        meta_dict = {
+
+        # default description -> docstring
+        description = (
+            (inspect.getdoc(tool) or "").strip()
+            if not (metadata and "description" in metadata)
+            else None
+        )
+
+        meta_dict: Dict[str, Any] = {
             "name": key,
             "namespace": namespace,
-            "is_async": is_async
+            "is_async": is_async,
         }
-        
-        # Add description if available (but don't override metadata if provided)
-        if description and not (metadata and "description" in metadata):
+        if description:
             meta_dict["description"] = description
-            
-        # Add any additional metadata
         if metadata:
             meta_dict.update(metadata)
-            
-        tool_metadata = ToolMetadata(**meta_dict)
-        
-        self._metadata[namespace][key] = tool_metadata
+
+        self._metadata[namespace][key] = ToolMetadata(**meta_dict)
+
+    # ------------------------------------------------------------------ #
+    # retrieval
+    # ------------------------------------------------------------------ #
 
     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.
-        """
-        if namespace not in self._tools:
-            return None
-        return self._tools[namespace].get(name)
+        return self._tools.get(namespace, {}).get(name)
 
     def get_tool_strict(self, name: str, namespace: str = "default") -> Any:
-        """
-        Retrieve a registered tool by name and namespace, raising an exception if not found.
-        
-        Args:
-            name: The name of the tool.
-            namespace: The namespace of the tool (default: "default").
-            
-        Returns:
-            The tool implementation.
-            
-        Raises:
-            ToolNotFoundError: If the tool is not found.
-        """
         tool = self.get_tool(name, namespace)
         if tool is None:
             raise ToolNotFoundError(f"{namespace}.{name}")
         return tool
 
-    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.
-        """
-        if namespace not in self._metadata:
-            return None
-        return self._metadata[namespace].get(name)
+    def get_metadata(
+        self, name: str, namespace: str = "default"
+    ) -> Optional[ToolMetadata]:
+        return self._metadata.get(namespace, {}).get(name)
+
+    # ------------------------------------------------------------------ #
+    # listing helpers
+    # ------------------------------------------------------------------ #
 
     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.
+        Return a list of ``(namespace, name)`` tuples.
         """
-        result = []
-        
         if namespace:
-            # List tools in specific namespace
-            if namespace in self._tools:
-                for name in self._tools[namespace].keys():
-                    result.append((namespace, name))
-        else:
-            # List all tools
-            for ns, tools in self._tools.items():
-                for name in tools.keys():
-                    result.append((ns, name))
-                    
+            return [
+                (namespace, n) for n in self._tools.get(namespace, {}).keys()
+            ]
+
+        result: List[Tuple[str, str]] = []
+        for ns, tools in self._tools.items():
+            result.extend((ns, n) for n in tools.keys())
         return result
 
     def list_namespaces(self) -> List[str]:
+        return list(self._tools.keys())
+
+    def list_metadata(self, namespace: str | None = None) -> List[ToolMetadata]:
         """
-        List all registered namespaces.
-        
-        Returns:
-            List of namespace names.
+        Return *all* :class:`ToolMetadata` objects.
+
+        Parameters
+        ----------
+        namespace
+            • ``None`` *(default)* – metadata from **all** namespaces  
+            • ``"some_ns"``        – only that namespace
         """
-        return list(self._tools.keys())
+        if namespace is not None:
+            return list(self._metadata.get(namespace, {}).values())
+
+        # flatten
+        result: List[ToolMetadata] = []
+        for ns_meta in self._metadata.values():
+            result.extend(ns_meta.values())
+        return result