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

chuk_tool_processor/registry/providers/memory.py

@@ -1,11 +1,10 @@
 # chuk_tool_processor/registry/providers/memory.py
-# chuk_tool_processor/registry/providers/memory.py
 """
-In-memory implementation of the tool registry.
+In-memory implementation of the asynchronous tool registry.
 """
-
 from __future__ import annotations
 
+import asyncio
 import inspect
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -16,9 +15,10 @@ from chuk_tool_processor.registry.metadata import ToolMetadata
 
 class InMemoryToolRegistry(ToolRegistryInterface):
     """
-    In-memory implementation of ToolRegistryInterface with namespace support.
+    In-memory implementation of the async ToolRegistryInterface with namespace support.
 
     Suitable for single-process apps or tests; not persisted across processes.
+    Thread-safe with asyncio locking.
     """
 
     # ------------------------------------------------------------------ #
@@ -30,72 +30,80 @@ class InMemoryToolRegistry(ToolRegistryInterface):
         self._tools: Dict[str, Dict[str, Any]] = {}
         # {namespace: {tool_name: ToolMetadata}}
         self._metadata: Dict[str, Dict[str, ToolMetadata]] = {}
+        # Lock for thread safety
+        self._lock = asyncio.Lock()
 
     # ------------------------------------------------------------------ #
     # registration
     # ------------------------------------------------------------------ #
 
-    def register_tool(
+    async def register_tool(
         self,
         tool: Any,
         name: Optional[str] = None,
         namespace: str = "default",
         metadata: Optional[Dict[str, Any]] = None,
     ) -> None:
-        # ensure namespace buckets
-        self._tools.setdefault(namespace, {})
-        self._metadata.setdefault(namespace, {})
-
-        key = name or getattr(tool, "__name__", None) or repr(tool)
-        self._tools[namespace][key] = tool
-
-        # build metadata -------------------------------------------------
-        is_async = inspect.iscoroutinefunction(getattr(tool, "execute", None))
-
-        # 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,
-        }
-        if description:
-            meta_dict["description"] = description
-        if metadata:
-            meta_dict.update(metadata)
-
-        self._metadata[namespace][key] = ToolMetadata(**meta_dict)
+        """Register a tool in the registry asynchronously."""
+        async with self._lock:
+            # ensure namespace buckets
+            self._tools.setdefault(namespace, {})
+            self._metadata.setdefault(namespace, {})
+
+            key = name or getattr(tool, "__name__", None) or repr(tool)
+            self._tools[namespace][key] = tool
+
+            # build metadata -------------------------------------------------
+            is_async = inspect.iscoroutinefunction(getattr(tool, "execute", None))
+
+            # 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,
+            }
+            if description:
+                meta_dict["description"] = description
+            if metadata:
+                meta_dict.update(metadata)
+
+            self._metadata[namespace][key] = ToolMetadata(**meta_dict)
 
     # ------------------------------------------------------------------ #
     # retrieval
     # ------------------------------------------------------------------ #
 
-    def get_tool(self, name: str, namespace: str = "default") -> Optional[Any]:
+    async def get_tool(self, name: str, namespace: str = "default") -> Optional[Any]:
+        """Retrieve a tool by name and namespace asynchronously."""
+        # Read operations don't need locking for better concurrency
         return self._tools.get(namespace, {}).get(name)
 
-    def get_tool_strict(self, name: str, namespace: str = "default") -> Any:
-        tool = self.get_tool(name, namespace)
+    async def get_tool_strict(self, name: str, namespace: str = "default") -> Any:
+        """Get a tool with strict validation, raising if not found."""
+        tool = await self.get_tool(name, namespace)
         if tool is None:
             raise ToolNotFoundError(f"{namespace}.{name}")
         return tool
 
-    def get_metadata(
+    async def get_metadata(
         self, name: str, namespace: str = "default"
     ) -> Optional[ToolMetadata]:
+        """Get metadata for a tool asynchronously."""
         return self._metadata.get(namespace, {}).get(name)
 
     # ------------------------------------------------------------------ #
     # listing helpers
     # ------------------------------------------------------------------ #
 
-    def list_tools(self, namespace: Optional[str] = None) -> List[Tuple[str, str]]:
+    async def list_tools(self, namespace: Optional[str] = None) -> List[Tuple[str, str]]:
         """
-        Return a list of ``(namespace, name)`` tuples.
+        Return a list of ``(namespace, name)`` tuples asynchronously.
         """
         if namespace:
             return [
@@ -107,18 +115,21 @@ class InMemoryToolRegistry(ToolRegistryInterface):
             result.extend((ns, n) for n in tools.keys())
         return result
 
-    def list_namespaces(self) -> List[str]:
+    async def list_namespaces(self) -> List[str]:
+        """List all namespaces asynchronously."""
         return list(self._tools.keys())
 
-    def list_metadata(self, namespace: str | None = None) -> List[ToolMetadata]:
+    async def list_metadata(self, namespace: Optional[str] = None) -> List[ToolMetadata]:
         """
-        Return *all* :class:`ToolMetadata` objects.
+        Return all ToolMetadata objects asynchronously.
 
-        Parameters
-        ----------
-        namespace
-            • ``None`` *(default)* – metadata from **all** namespaces  
-            • ``"some_ns"``        – only that namespace
+        Args:
+            namespace: Optional filter by namespace.
+                • None (default) – metadata from all namespaces
+                • "some_ns" – only that namespace
+
+        Returns:
+            List of ToolMetadata objects.
         """
         if namespace is not None:
             return list(self._metadata.get(namespace, {}).values())
@@ -127,4 +138,4 @@ class InMemoryToolRegistry(ToolRegistryInterface):
         result: List[ToolMetadata] = []
         for ns_meta in self._metadata.values():
             result.extend(ns_meta.values())
-        return result
+        return result

chuk_tool_processor/registry/tool_export.py

@@ -1,46 +1,77 @@
 # chuk_tool_processor/registry/tool_export.py
 """
-Helpers that expose all registered tools in various formats and
+Async helpers that expose all registered tools in various formats and
 translate an OpenAI `function.name` back to the matching tool.
 """
 from __future__ import annotations
 
-from typing import Dict, List
+import asyncio
+from typing import Dict, List, Any, Optional, Mapping
 
+# registry
 from .provider import ToolRegistryProvider
 
 # --------------------------------------------------------------------------- #
-# internal cache so tool-name lookup is O(1)
+# internal cache so tool-name lookup is O(1) with async protection
 # --------------------------------------------------------------------------- #
-_OPENAI_NAME_CACHE: dict[str, object] | None = None
+_OPENAI_NAME_CACHE: Optional[Dict[str, Any]] = None
+_CACHE_LOCK = asyncio.Lock()
 
 
-def _build_openai_name_cache() -> None:
-    """Populate the global reverse-lookup table once."""
+async def _build_openai_name_cache() -> None:
+    """
+    Populate the global reverse-lookup table once asynchronously.
+    
+    This function is thread-safe and will only build the cache once,
+    even with concurrent calls.
+    """
     global _OPENAI_NAME_CACHE
-    if _OPENAI_NAME_CACHE is not None:  # already built
+    
+    # Fast path - cache already exists
+    if _OPENAI_NAME_CACHE is not None:
         return
 
-    _OPENAI_NAME_CACHE = {}
-    reg = ToolRegistryProvider.get_registry()
-
-    for ns, key in reg.list_tools():
-        tool = reg.get_tool(key, ns)
-
-        # ▸ registry key  -> tool
-        _OPENAI_NAME_CACHE[key] = tool
-
-        # ▸ class name    -> tool  (legacy)
-        _OPENAI_NAME_CACHE[tool.__class__.__name__] = tool
-
-        # ▸ OpenAI name   -> tool  (may differ from both above)
-        _OPENAI_NAME_CACHE[tool.to_openai()["function"]["name"]] = tool
+    # Slow path - build the cache with proper locking
+    async with _CACHE_LOCK:
+        # Double-check pattern: check again after acquiring the lock
+        if _OPENAI_NAME_CACHE is not None:
+            return
+            
+        # Initialize an empty cache
+        _OPENAI_NAME_CACHE = {}
+        
+        # Get the registry
+        reg = await ToolRegistryProvider.get_registry()
+
+        # Get all tools and their names
+        tools_list = await reg.list_tools()
+        
+        for ns, key in tools_list:
+            # Get the tool
+            tool = await reg.get_tool(key, ns)
+            if tool is None:
+                continue
+
+            # ▸ registry key -> tool
+            _OPENAI_NAME_CACHE[key] = tool
+
+            # ▸ class name -> tool (legacy)
+            _OPENAI_NAME_CACHE[tool.__class__.__name__] = tool
+
+            # ▸ OpenAI name -> tool (may differ from both above)
+            try:
+                openai_spec = tool.to_openai()
+                openai_name = openai_spec["function"]["name"]
+                _OPENAI_NAME_CACHE[openai_name] = tool
+            except (AttributeError, KeyError, TypeError):
+                # Skip tools that don't have proper OpenAI specs
+                pass
 
 
 # --------------------------------------------------------------------------- #
 # public helpers
 # --------------------------------------------------------------------------- #
-def openai_functions() -> List[Dict]:
+async def openai_functions() -> List[Dict]:
     """
     Return **all** registered tools in the exact schema the Chat-Completions
     API expects in its ``tools=[ … ]`` parameter.
@@ -48,29 +79,167 @@ def openai_functions() -> List[Dict]:
     The ``function.name`` is always the *registry key* so that the round-trip
     (export → model → parser) stays consistent even when the class name and
     the registered key differ.
+    
+    Returns:
+        List of OpenAI function specifications
     """
-    reg = ToolRegistryProvider.get_registry()
-    specs: list[dict] = []
-
-    for ns, key in reg.list_tools():
-        tool = reg.get_tool(key, ns)
-        spec = tool.to_openai()
-        spec["function"]["name"] = key  # ensure round-trip consistency
-        specs.append(spec)
-
-    # Ensure the cache is built the first time we export
-    _build_openai_name_cache()
+    # Get the registry
+    reg = await ToolRegistryProvider.get_registry()
+    specs: List[Dict[str, Any]] = []
+
+    # List all tools
+    tools_list = await reg.list_tools()
+    
+    for ns, key in tools_list:
+        # Get each tool
+        tool = await reg.get_tool(key, ns)
+        if tool is None:
+            continue
+            
+        try:
+            # Get the OpenAI spec
+            spec = tool.to_openai()
+            # Override the name to ensure round-trip consistency
+            spec["function"]["name"] = key
+            specs.append(spec)
+        except (AttributeError, TypeError):
+            # Skip tools that don't support OpenAI format
+            pass
+
+    # Ensure the cache is built
+    await _build_openai_name_cache()
     return specs
 
 
-def tool_by_openai_name(name: str):
+async def tool_by_openai_name(name: str) -> Any:
     """
-    Map an OpenAI ``function.name`` back to the registered tool.
-
-    Raises ``KeyError`` if the name is unknown.
+    Map an OpenAI ``function.name`` back to the registered tool asynchronously.
+
+    Args:
+        name: The OpenAI function name
+        
+    Returns:
+        The tool implementation
+        
+    Raises:
+        KeyError: If the name is unknown
     """
-    _build_openai_name_cache()
+    # Ensure the cache is built
+    await _build_openai_name_cache()
+    
+    # Look up the tool
     try:
-        return _OPENAI_NAME_CACHE[name]  # type: ignore[index]
+        if _OPENAI_NAME_CACHE is None:
+            raise KeyError(f"Tool cache not initialized")
+            
+        return _OPENAI_NAME_CACHE[name]
     except (KeyError, TypeError):
         raise KeyError(f"No tool registered for OpenAI name {name!r}") from None
+
+
+async def clear_name_cache() -> None:
+    """
+    Clear the OpenAI name cache.
+    
+    This is useful in tests or when the registry changes significantly.
+    """
+    global _OPENAI_NAME_CACHE
+    async with _CACHE_LOCK:
+        _OPENAI_NAME_CACHE = None
+
+
+async def export_tools_as_openapi(
+    title: str = "Tool API",
+    version: str = "1.0.0",
+    description: str = "API for registered tools",
+) -> Dict[str, Any]:
+    """
+    Export all registered tools as an OpenAPI specification.
+    
+    Args:
+        title: API title
+        version: API version
+        description: API description
+        
+    Returns:
+        OpenAPI specification as a dictionary
+    """
+    # Get the registry
+    reg = await ToolRegistryProvider.get_registry()
+    
+    # Build paths and components
+    paths: Dict[str, Any] = {}
+    schemas: Dict[str, Any] = {}
+    
+    # List all tools
+    tools_list = await reg.list_tools()
+    
+    for ns, key in tools_list:
+        # Get tool and metadata
+        tool = await reg.get_tool(key, ns)
+        metadata = await reg.get_metadata(key, ns)
+        
+        if tool is None or metadata is None:
+            continue
+            
+        # Create path
+        path = f"/{ns}/{key}"
+        
+        # Get schemas from tool if available
+        arg_schema = None
+        result_schema = None
+        
+        if hasattr(tool, "Arguments") and hasattr(tool.Arguments, "model_json_schema"):
+            arg_schema = tool.Arguments.model_json_schema()
+            schemas[f"{key}Args"] = arg_schema
+            
+        if hasattr(tool, "Result") and hasattr(tool.Result, "model_json_schema"):
+            result_schema = tool.Result.model_json_schema()
+            schemas[f"{key}Result"] = result_schema
+        
+        # Add path
+        paths[path] = {
+            "post": {
+                "summary": metadata.description or f"Execute {key}",
+                "operationId": f"execute_{ns}_{key}",
+                "tags": [ns],
+                "requestBody": {
+                    "required": True,
+                    "content": {
+                        "application/json": {
+                            "schema": {"$ref": f"#/components/schemas/{key}Args"} if arg_schema else {}
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {"$ref": f"#/components/schemas/{key}Result"} if result_schema else {}
+                            }
+                        }
+                    },
+                    "400": {
+                        "description": "Bad request"
+                    },
+                    "500": {
+                        "description": "Internal server error"
+                    }
+                }
+            }
+        }
+    
+    # Build the OpenAPI spec
+    return {
+        "openapi": "3.0.0",
+        "info": {
+            "title": title,
+            "version": version,
+            "description": description
+        },
+        "paths": paths,
+        "components": {
+            "schemas": schemas
+        }
+    }

chuk_tool_processor/utils/validation.py

@@ -1,6 +1,6 @@
 # chuk_tool_processor/utils/validation.py
 """
-Runtime helpers for validating tool inputs / outputs with Pydantic.
+Async runtime helpers for validating tool inputs / outputs with Pydantic.
 
 Public API
 ----------
@@ -10,11 +10,12 @@ validate_result(tool_name, fn, result)  -> Any
 """
 from __future__ import annotations
 import inspect
+import asyncio
 from functools import lru_cache, wraps
-from typing import Any, Callable, Dict, get_type_hints
+from typing import Any, Callable, Dict, get_type_hints, Awaitable
 from pydantic import BaseModel, ValidationError, create_model, Extra
 
-# excpetion
+# exception
 from chuk_tool_processor.core.exceptions import ToolValidationError
 
 __all__ = [
@@ -66,19 +67,21 @@ def _result_model(tool_name: str, fn: Callable) -> type[BaseModel] | None:
 
 
 # --------------------------------------------------------------------------- #
-# public validation helpers
+# public validation helpers - synced with async patterns
 # --------------------------------------------------------------------------- #
 
 
 def validate_arguments(tool_name: str, fn: Callable, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Validate function arguments against type hints."""
     try:
         model = _arg_model(tool_name, fn)
-        return model(**args).dict()
+        return model(**args).model_dump()
     except ValidationError as exc:
         raise ToolValidationError(tool_name, exc.errors()) from exc
 
 
 def validate_result(tool_name: str, fn: Callable, result: Any) -> Any:
+    """Validate function return value against return type hint."""
     model = _result_model(tool_name, fn)
     if model is None:  # no annotation ⇒ no validation
         return result
@@ -89,33 +92,35 @@ def validate_result(tool_name: str, fn: Callable, result: Any) -> Any:
 
 
 # --------------------------------------------------------------------------- #
-# decorator for classic “imperative” tools
+# decorator for classic "imperative" tools - now requires async
 # --------------------------------------------------------------------------- #
 
 
 def with_validation(cls):
     """
-    Wrap *execute* / *_execute* so that their arguments & return values
-    are type-checked each call.
+    Wrap an async *execute* method with argument & result validation.
 
     ```
     @with_validation
     class MyTool:
-        def execute(self, x: int, y: int) -> int:
+        async def execute(self, x: int, y: int) -> int:
             return x + y
     ```
     """
-
     # Which method did the user provide?
     fn_name = "_execute" if hasattr(cls, "_execute") else "execute"
     original = getattr(cls, fn_name)
+    
+    # Ensure the method is async
+    if not inspect.iscoroutinefunction(original):
+        raise TypeError(f"Tool {cls.__name__} must have an async {fn_name} method")
 
     @wraps(original)
-    def _validated(self, **kwargs):
+    async def _validated(self, **kwargs):
         name = cls.__name__
         kwargs = validate_arguments(name, original, kwargs)
-        res = original(self, **kwargs)
+        res = await original(self, **kwargs)
         return validate_result(name, original, res)
 
     setattr(cls, fn_name, _validated)
-    return cls
+    return cls