chuk-tool-processor 0.1.6__py3-none-any.whl → 0.2__py3-none-any.whl

chuk_tool_processor/plugins/parsers/base.py

@@ -1,18 +1,26 @@
 # chuk_tool_processor/parsers/base.py
+"""Async-native parser-plugin base interface."""
+
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from typing import List
+
 from chuk_tool_processor.models.tool_call import ToolCall
 
+__all__ = ["ParserPlugin"]
+
 
 class ParserPlugin(ABC):
     """
-    Minimal interface every parser plug-in must implement.
+    Every parser plugin **must** implement the async ``try_parse`` coroutine.
 
-    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.
+    The processor awaits it and expects *a list* of :class:`ToolCall`
+    objects. If the plugin doesn’t recognise the input it should return an
+    empty list.
     """
 
     @abstractmethod
-    def try_parse(self, raw: str) -> List[ToolCall]:
+    async def try_parse(self, raw: str | object) -> List[ToolCall]:  # noqa: D401
+        """Attempt to parse *raw* into one or more :class:`ToolCall` objects."""
         ...

chuk_tool_processor/plugins/parsers/{function_call_tool_plugin.py → function_call_tool.py}

@@ -1,33 +1,49 @@
-# 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*.
-"""
+# chuk_tool_processor/plugins/parsers/function_call_tool.py
+"""Async parser for OpenAI-style single `function_call` objects."""
+
 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
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.plugins.parsers.base import ParserPlugin
+
+__all__ = ["FunctionCallPlugin"]
 
-# logger
-logger = get_logger("chuk_tool_processor.plugins.function_call_tool")
+logger = get_logger(__name__)
 
-# balanced‐brace JSON object regex – one level only (good enough for payloads)
+# One-level balanced JSON object (good enough for embedded argument blocks)
 _JSON_OBJECT = re.compile(r"\{(?:[^{}]|(?:\{[^{}]*\}))*\}")
 
 
+class PluginMeta:
+    """Optional self-description used by the plugin-discovery system (if present)."""
+
+    name: str = "function_call"
+    description: str = (
+        "Parses a single OpenAI-style `function_call` JSON object (including "
+        "strings that embed such an object)."
+    )
+    version: str = "1.0.0"
+    author: str = "chuk_tool_processor"
+
+
 class FunctionCallPlugin(ParserPlugin):
-    """Parse OpenAI-style **single** ``function_call`` objects."""
+    """Parse messages containing a *single* `function_call` entry."""
+
+    # --------------------------------------------------------------------- #
+    # Public API
+    # --------------------------------------------------------------------- #
 
-    def try_parse(self, raw: str | Dict[str, Any]) -> List[ToolCall]:
+    async def try_parse(self, raw: str | Dict[str, Any]) -> List[ToolCall]:
         payload: Dict[str, Any] | None
+
+        # 1️⃣  Primary path ─ whole payload is JSON
         if isinstance(raw, dict):
             payload = raw
         else:
@@ -38,22 +54,24 @@ class FunctionCallPlugin(ParserPlugin):
 
         calls: List[ToolCall] = []
 
-        # primary path -----------------------------------------------------
         if isinstance(payload, dict):
             calls.extend(self._extract_from_payload(payload))
 
-        # fallback – scan raw text for nested JSON blocks ------------------
+        # 2️⃣  Fallback path ─ scan for *nested* JSON objects inside a string
         if not calls and isinstance(raw, str):
-            for m in _JSON_OBJECT.finditer(raw):
+            for match in _JSON_OBJECT.finditer(raw):
                 try:
-                    sub = json.loads(m.group(0))
+                    sub = json.loads(match.group(0))
                 except json.JSONDecodeError:
                     continue
                 calls.extend(self._extract_from_payload(sub))
 
         return calls
 
-    # ------------------------------------------------------------------
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+
     def _extract_from_payload(self, payload: Dict[str, Any]) -> List[ToolCall]:
         fc = payload.get("function_call")
         if not isinstance(fc, dict):
@@ -62,12 +80,13 @@ class FunctionCallPlugin(ParserPlugin):
         name = fc.get("name")
         args = fc.get("arguments", {})
 
-        # arguments may be JSON‑encoded string or anything else
+        # Arguments may themselves be JSON in *string* form
         if isinstance(args, str):
             try:
                 args = json.loads(args)
             except json.JSONDecodeError:
                 args = {}
+
         if not isinstance(args, dict):
             args = {}
 

chuk_tool_processor/plugins/parsers/json_tool.py

@@ -0,0 +1,50 @@
+# chuk_tool_processor/plugins/parsers/json_tool.py
+"""Async JSON `tool_calls` parser plugin."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, List
+
+from pydantic import ValidationError
+
+from chuk_tool_processor.logging import get_logger
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.plugins.parsers.base import ParserPlugin
+
+__all__ = ["JsonToolPlugin"]
+
+logger = get_logger(__name__)
+
+
+class PluginMeta:
+    """Optional self-description consumed by the plugin-discovery subsystem."""
+    name: str = "json_tool_calls"
+    description: str = "Parses a JSON object containing a `tool_calls` array."
+    version: str = "1.0.0"
+    author: str = "chuk_tool_processor"
+
+
+class JsonToolPlugin(ParserPlugin):
+    """Extracts a *list* of :class:`ToolCall` objects from a `tool_calls` array."""
+
+    async def try_parse(self, raw: str | Any) -> List[ToolCall]:  # noqa: D401
+        # Decode JSON if we were given a string
+        try:
+            data = json.loads(raw) if isinstance(raw, str) else raw
+        except json.JSONDecodeError:
+            logger.debug("json_tool: input is not valid JSON")
+            return []
+
+        if not isinstance(data, dict):
+            return []
+
+        calls: List[ToolCall] = []
+        for entry in data.get("tool_calls", []):
+            try:
+                calls.append(ToolCall(**entry))
+            except ValidationError:
+                logger.debug("json_tool: validation error on entry %s", entry)
+                continue
+
+        return calls

chuk_tool_processor/plugins/parsers/openai_tool.py

@@ -0,0 +1,88 @@
+# chuk_tool_processor/plugins/parsers/openai_tool.py
+"""Async parser for OpenAI-style `tool_calls` arrays."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, List
+
+from pydantic import ValidationError
+
+from chuk_tool_processor.logging import get_logger
+from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.plugins.parsers.base import ParserPlugin
+
+__all__ = ["OpenAIToolPlugin"]
+
+logger = get_logger(__name__)
+
+
+class PluginMeta:
+    """Optional descriptor consumed by the plugin-discovery system."""
+    name: str = "openai_tool_calls"
+    description: str = "Parses Chat-Completions responses containing `tool_calls`."
+    version: str = "1.0.0"
+    author: str = "chuk_tool_processor"
+
+
+class OpenAIToolPlugin(ParserPlugin):
+    """
+    Understands structures like::
+
+        {
+            "tool_calls": [
+                {
+                    "id": "call_abc",
+                    "type": "function",
+                    "function": {
+                        "name": "weather",
+                        "arguments": "{\"location\": \"New York\"}"
+                    }
+                }
+            ]
+        }
+    """
+
+    async def try_parse(self, raw: str | Any) -> List[ToolCall]:  # noqa: D401
+        # ------------------------------------------------------------------ #
+        # 1. Decode JSON when the input is a string
+        # ------------------------------------------------------------------ #
+        try:
+            data = json.loads(raw) if isinstance(raw, str) else raw
+        except json.JSONDecodeError:
+            logger.debug("openai_tool_plugin: input is not valid JSON")
+            return []
+
+        if not isinstance(data, dict) or "tool_calls" not in data:
+            return []
+
+        # ------------------------------------------------------------------ #
+        # 2. Build ToolCall objects
+        # ------------------------------------------------------------------ #
+        calls: List[ToolCall] = []
+        for entry in data["tool_calls"]:
+            fn = entry.get("function", {})
+            name = fn.get("name")
+            args = fn.get("arguments", {})
+
+            # Arguments may be double-encoded JSON
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except json.JSONDecodeError:
+                    args = {}
+
+            if not isinstance(name, str) or not name:
+                continue
+
+            try:
+                calls.append(
+                    ToolCall(tool=name, arguments=args if isinstance(args, dict) else {})
+                )
+            except ValidationError:
+                logger.debug(
+                    "openai_tool_plugin: validation error while building ToolCall for %s",
+                    name,
+                )
+
+        return calls

chuk_tool_processor/plugins/parsers/xml_tool.py

@@ -1,45 +1,99 @@
-# chuk_tool_processor/plugins/xml_tool.py
-"""XML tool-call parser plugin.
-Understands `<tool name="..." args='{"x":1}'/>` single-line constructs –
-format used by many examples and test-fixtures.
+# chuk_tool_processor/plugins/parsers/xml_tool.py
 """
+Async-native parser for single-line XML-style tool-call tags, e.g.
+
+    <tool name="translate" args="{\"text\": \"Hello\", \"target\": \"es\"}"/>
+
+The *args* attribute may be
+
+1. A proper JSON object:                   args="{"x": 1}"
+2. A JSON-encoded string (most common):    args="{\"x\": 1}"
+3. The empty string:                       args=""
+
+All variants are normalised to a **dict** of arguments.
+"""
+
 from __future__ import annotations
 
 import json
 import re
 from typing import List
+
 from pydantic import ValidationError
 
-# imports
-from .base import ParserPlugin
+from chuk_tool_processor.logging import get_logger
 from chuk_tool_processor.models.tool_call import ToolCall
+from chuk_tool_processor.plugins.parsers.base import ParserPlugin
+
+__all__: list[str] = ["XmlToolPlugin"]
+
+logger = get_logger(__name__)
 
 
+class PluginMeta:
+    """Optional descriptor that can be used by the plugin-discovery mechanism."""
+    name: str = "xml_tool_tag"
+    description: str = "Parses <tool …/> XML tags into ToolCall objects."
+    version: str = "1.0.0"
+    author: str = "chuk_tool_processor"
+
 
 class XmlToolPlugin(ParserPlugin):
-    """Parse XML-like tool-call tags."""
+    """Convert `<tool …/>` tags into :class:`ToolCall` objects."""
 
     _TAG = re.compile(
         r"<tool\s+"
-        r"name=(?P<q1>[\"\'])(?P<tool>.+?)(?P=q1)\s+"
-        r"args=(?P<q2>[\"\'])(?P<args>.*?)(?P=q2)\s*/>"
+        r"name=(?P<q1>[\"'])(?P<tool>.+?)(?P=q1)\s+"
+        r"args=(?P<q2>[\"'])(?P<args>.*?)(?P=q2)\s*/>",
+        flags=re.IGNORECASE | re.DOTALL,
     )
 
-    def try_parse(self, raw):  # type: ignore[override]
-        if not isinstance(raw, str):  # XML form only exists in strings
+    # ------------------------------------------------------------------ #
+    async def try_parse(self, raw: str | object) -> List[ToolCall]:  # noqa: D401
+        if not isinstance(raw, str):
             return []
 
         calls: List[ToolCall] = []
-        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:
-                args = {}
+
+        for match in self._TAG.finditer(raw):
+            name = match.group("tool")
+            raw_args = match.group("args") or ""
+            args = self._decode_args(raw_args)
 
             try:
-                calls.append(ToolCall(tool=tool_name, arguments=args))
+                calls.append(ToolCall(tool=name, arguments=args))
             except ValidationError:
-                continue  # skip malformed
+                logger.debug("xml_tool_plugin: validation error for <%s>", name)
+
         return calls
+
+    # ------------------------------------------------------------------ #
+    # Helper – robust JSON decode for the args attribute
+    # ------------------------------------------------------------------ #
+    @staticmethod
+    def _decode_args(raw_args: str) -> dict:
+        """Best-effort decoding of the *args* attribute to a dict."""
+        if not raw_args:
+            return {}
+
+        # 1️⃣ Try direct JSON
+        try:
+            parsed = json.loads(raw_args)
+        except json.JSONDecodeError:
+            parsed = None
+
+        # 2️⃣ If still None, the value might be a JSON-encoded string
+        if parsed is None:
+            try:
+                parsed = json.loads(raw_args.encode().decode("unicode_escape"))
+            except json.JSONDecodeError:
+                parsed = None
+
+        # 3️⃣ Last resort – naive unescaping of \" → "
+        if parsed is None:
+            try:
+                parsed = json.loads(raw_args.replace(r"\"", "\""))
+            except json.JSONDecodeError:
+                parsed = {}
+
+        return parsed if isinstance(parsed, dict) else {}

chuk_tool_processor/registry/__init__.py

@@ -1,21 +1,60 @@
+# chuk_tool_processor/registry/__init__.py
 """
-Tool registry package for managing and accessing tool implementations.
+Async-native tool registry package for managing and accessing tool implementations.
 """
 
+import asyncio
+from typing import Optional
+
 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.metadata import ToolMetadata, StreamingToolMetadata
+from chuk_tool_processor.registry.provider import ToolRegistryProvider, get_registry
+from chuk_tool_processor.registry.decorators import register_tool, ensure_registrations, discover_decorated_tools
 
 # --------------------------------------------------------------------------- #
-# Expose the *singleton* registry that every part of the library should use
+# The default_registry is now an async function instead of direct property access
 # --------------------------------------------------------------------------- #
-default_registry = ToolRegistryProvider.get_registry()
+async def get_default_registry() -> ToolRegistryInterface:
+    """
+    Get the default registry instance.
+    
+    This is a convenience function that calls ToolRegistryProvider.get_registry()
+    
+    Returns:
+        The default tool registry
+    """
+    return await ToolRegistryProvider.get_registry()
 
 __all__ = [
     "ToolRegistryInterface",
     "ToolMetadata",
+    "StreamingToolMetadata",
     "ToolRegistryProvider",
     "register_tool",
-    "default_registry",
+    "ensure_registrations",
+    "discover_decorated_tools",
+    "get_default_registry",
+    "get_registry",
 ]
+
+# --------------------------------------------------------------------------- #
+# Initialization helper that should be called at application startup
+# --------------------------------------------------------------------------- #
+async def initialize():
+    """
+    Initialize the registry system.
+    
+    This function should be called during application startup to:
+    1. Ensure the registry is created
+    2. Register all tools decorated with @register_tool
+    
+    Returns:
+        The initialized registry
+    """
+    # Initialize registry
+    registry = await get_default_registry()
+    
+    # Process all pending tool registrations
+    await ensure_registrations()
+    
+    return registry

chuk_tool_processor/registry/auto_register.py

@@ -1,11 +1,12 @@
 # chuk_tool_processor/registry/auto_register.py
 """
-Tiny “auto-register” helpers so you can do
+Async auto-register helpers for registering functions and LangChain tools.
 
-    register_fn_tool(my_function)
-    register_langchain_tool(my_langchain_tool)
+Usage:
+    await register_fn_tool(my_function)
+    await register_langchain_tool(my_langchain_tool)
 
-and they immediately show up in the global registry.
+These tools will immediately show up in the global registry.
 """
 
 from __future__ import annotations
@@ -13,7 +14,7 @@ from __future__ import annotations
 import asyncio
 import inspect
 import types
-from typing import Callable, ForwardRef, Type, get_type_hints
+from typing import Callable, ForwardRef, Type, get_type_hints, Any, Optional, Dict, Union
 
 import anyio
 from pydantic import BaseModel, create_model
@@ -23,7 +24,9 @@ try:  # optional dependency
 except ModuleNotFoundError:  # pragma: no cover
     BaseTool = None  # noqa: N816  – keep the name for isinstance() checks
 
-from chuk_tool_processor.registry.decorators import register_tool
+# registry
+from .decorators import register_tool
+from .provider import ToolRegistryProvider
 
 
 # ────────────────────────────────────────────────────────────────────────────
@@ -37,7 +40,7 @@ def _auto_schema(func: Callable) -> Type[BaseModel]:
 
     *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
+    LangChain's `CallbackManagerForToolRun`) default to ``str`` instead of
     crashing `get_type_hints()`.
     """
     try:
@@ -49,14 +52,14 @@ def _auto_schema(func: Callable) -> Type[BaseModel]:
     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.
+        # 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
+        fields[param.name] = (hint, ...)  # "..."  → required
 
     return create_model(f"{func.__name__.title()}Args", **fields)  # type: ignore
 
@@ -66,25 +69,54 @@ def _auto_schema(func: Callable) -> Type[BaseModel]:
 # ────────────────────────────────────────────────────────────────────────────
 
 
-def register_fn_tool(
+async def register_fn_tool(
     func: Callable,
     *,
     name: str | None = None,
     description: str | None = None,
+    namespace: str = "default",
 ) -> None:
-    """Register a plain function as a tool – one line is all you need."""
-
+    """
+    Register a plain function as a tool asynchronously.
+    
+    Args:
+        func: The function to register (can be sync or async)
+        name: Optional name for the tool (defaults to function name)
+        description: Optional description (defaults to function docstring)
+        namespace: Registry namespace (defaults to "default")
+    """
     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)
+    tool_name = name or func.__name__
+    tool_description = (description or func.__doc__ or "").strip()
+    
+    # Create the tool wrapper class
     class _Tool:  # noqa: D401, N801 – internal auto-wrapper
-        async def _execute(self, **kwargs):
+        """Auto-generated tool wrapper for function."""
+        
+        async def execute(self, **kwargs: Any) -> Any:
+            """Execute the wrapped function."""
             if inspect.iscoroutinefunction(func):
                 return await func(**kwargs)
             # off-load blocking sync work
             return await anyio.to_thread.run_sync(func, **kwargs)
+    
+    # Set the docstring
+    _Tool.__doc__ = tool_description
+    
+    # Get the registry and register directly
+    registry = await ToolRegistryProvider.get_registry()
+    await registry.register_tool(
+        _Tool(),
+        name=tool_name,
+        namespace=namespace,
+        metadata={
+            "description": tool_description,
+            "is_async": True,
+            "argument_schema": schema.model_json_schema(),
+            "source": "function",
+            "source_name": func.__qualname__,
+        }
+    )
 
 
 # ────────────────────────────────────────────────────────────────────────────
@@ -92,18 +124,27 @@ def register_fn_tool(
 # ────────────────────────────────────────────────────────────────────────────
 
 
-def register_langchain_tool(
-    tool,
+async def register_langchain_tool(
+    tool: Any,
     *,
     name: str | None = None,
     description: str | None = None,
+    namespace: str = "default",
 ) -> 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.
+    Register a **LangChain** `BaseTool` instance asynchronously.
+    
+    Works with any object exposing `.run` / `.arun` methods.
+
+    Args:
+        tool: The LangChain tool to register
+        name: Optional name for the tool (defaults to tool.name)
+        description: Optional description (defaults to tool.description)
+        namespace: Registry namespace (defaults to "default")
+        
+    Raises:
+        RuntimeError: If LangChain isn't installed
+        TypeError: If the object isn't a LangChain BaseTool
     """
     if BaseTool is None:
         raise RuntimeError(
@@ -117,9 +158,32 @@ def register_langchain_tool(
             f"{type(tool).__name__}"
         )
 
-    fn = tool.arun if hasattr(tool, "arun") else tool.run  # prefer async
-    register_fn_tool(
+    # Prefer async implementation if available
+    fn = tool.arun if hasattr(tool, "arun") else tool.run
+    
+    tool_name = name or tool.name or tool.__class__.__name__
+    tool_description = description or tool.description or (tool.__doc__ or "")
+    
+    await register_fn_tool(
         fn,
-        name=name or tool.name or tool.__class__.__name__,
-        description=description or tool.description or (tool.__doc__ or ""),
+        name=tool_name,
+        description=tool_description,
+        namespace=namespace,
     )
+    
+    # Update the metadata to include LangChain info
+    registry = await ToolRegistryProvider.get_registry()
+    metadata = await registry.get_metadata(tool_name, namespace)
+    
+    if metadata:
+        updated_metadata = metadata.model_copy()
+        # Update source info
+        updated_metadata.tags.add("langchain")
+        
+        # Re-register with updated metadata
+        await registry.register_tool(
+            await registry.get_tool(tool_name, namespace),
+            name=tool_name,
+            namespace=namespace,
+            metadata=updated_metadata.model_dump(),
+        )