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

chuk_tool_processor/registry/provider.py

@@ -1,5 +1,6 @@
+# chuk_tool_processor/registry/provider.py
 """
-Global access to *the* tool registry instance.
+Global access to the async tool registry instance.
 
 There are two public faces:
 
@@ -8,92 +9,130 @@ There are two public faces:
       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**.
+2.  **`ToolRegistryProvider` class**  
+    Provides static methods for async-safe access to the registry.
 
 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.
+* `await ToolRegistryProvider.set_registry(obj)` overrides subsequent retrievals.
+* `await ToolRegistryProvider.set_registry(None)` resets the cache so the next
+  `await get_registry()` call invokes (and honours any monkey-patched) factory.
 """
 from __future__ import annotations
 
-from typing import Optional
+import asyncio
+import importlib
+import sys
+from typing import Optional, Callable, Awaitable, Dict, Any
 
+# registry
 from .interface import ToolRegistryInterface
-from .providers.memory import InMemoryToolRegistry
 
 # --------------------------------------------------------------------------- #
 # Module-level singleton used by the helper functions
 # --------------------------------------------------------------------------- #
 _REGISTRY: Optional[ToolRegistryInterface] = None
+_REGISTRY_LOCK = asyncio.Lock()
 # --------------------------------------------------------------------------- #
 
 
-def _default_registry() -> ToolRegistryInterface:
-    """Create the default in-memory registry."""
+async def _default_registry() -> ToolRegistryInterface:
+    """Create the default in-memory registry asynchronously."""
+    # Import here to avoid circular import
+    from .providers.memory import InMemoryToolRegistry
     return InMemoryToolRegistry()
 
 
-def get_registry() -> ToolRegistryInterface:
+async def get_registry() -> ToolRegistryInterface:
     """
-    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.
+    Return the process-wide registry asynchronously, creating it on first use.
+    
+    This function is thread-safe and will only create the registry once,
+    even with concurrent calls.
     """
     global _REGISTRY
     if _REGISTRY is None:
-        _REGISTRY = _default_registry()
+        async with _REGISTRY_LOCK:
+            # Double-check pattern: check again after acquiring the lock
+            if _REGISTRY is None:
+                _REGISTRY = await _default_registry()
     return _REGISTRY
 
 
-def set_registry(registry: ToolRegistryInterface | None) -> None:
+async def set_registry(registry: ToolRegistryInterface | None) -> None:
     """
-    Replace or clear the global registry.
+    Replace or clear the global registry asynchronously.
 
     Passing ``None`` resets the singleton so that the next `get_registry()`
     call recreates it (useful in tests).
     """
     global _REGISTRY
-    _REGISTRY = registry
+    async with _REGISTRY_LOCK:
+        _REGISTRY = registry
 
 
 # --------------------------------------------------------------------------- #
-# Back-compat shim used by legacy import paths and the test-suite
+# Provider class for consistent access to the registry
 # --------------------------------------------------------------------------- #
-class ToolRegistryProvider:                       # noqa: D401
-    """Legacy static wrapper retaining historical semantics."""
+class ToolRegistryProvider:
+    """Async static wrapper for registry access."""
 
-    # The test-suite directly mutates this attribute, so we keep it.
+    # Thread-safe singleton management
     _registry: Optional[ToolRegistryInterface] = None
+    _lock = asyncio.Lock()
 
     # ------------------------ public API ------------------------ #
     @staticmethod
-    def get_registry() -> ToolRegistryInterface:
+    async def get_registry() -> ToolRegistryInterface:
         """
-        Return the cached instance or, if absent, call the *current*
-        module-level `get_registry()` exactly once to populate it.
+        Return the cached instance or initialize a new one asynchronously.
+        
+        This method ensures thread-safety when initializing the registry.
         """
         if ToolRegistryProvider._registry is None:
-            # Honour any runtime monkey-patching of the factory.
-            ToolRegistryProvider._registry = globals()["get_registry"]()
+            async with ToolRegistryProvider._lock:
+                # Check again after acquiring the lock
+                if ToolRegistryProvider._registry is None:
+                    # Dynamically import to get the latest definition
+                    module = sys.modules[__name__]
+                    get_registry_func: Callable[[], Awaitable[ToolRegistryInterface]] = getattr(
+                        module, "get_registry"
+                    )
+                    # Call it to get the registry
+                    ToolRegistryProvider._registry = await get_registry_func()
+        
         return ToolRegistryProvider._registry
 
     @staticmethod
-    def set_registry(registry: ToolRegistryInterface | None) -> None:
+    async def set_registry(registry: ToolRegistryInterface | None) -> None:
         """
-        Override the cached registry.
+        Override the cached registry asynchronously.
 
         *   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.
+            `get_registry()` call invokes the factory.
+        """
+        async with ToolRegistryProvider._lock:
+            ToolRegistryProvider._registry = registry
+            
+    @staticmethod
+    async def reset() -> None:
+        """
+        Reset both the module-level and class-level registry caches.
+        
+        This is primarily used in tests to ensure a clean state.
+        """
+        async with ToolRegistryProvider._lock:
+            ToolRegistryProvider._registry = None
+            await set_registry(None)
+            
+    @staticmethod
+    async def get_global_registry() -> ToolRegistryInterface:
+        """
+        Get the module-level registry directly.
+        
+        This bypasses the class-level cache and always returns the module-level registry.
         """
-        ToolRegistryProvider._registry = registry
+        return await get_registry()

chuk_tool_processor/registry/providers/__init__.py

@@ -1,20 +1,29 @@
+# chuk_tool_processor/registry/providers/__init__.py
 """
-Registry provider implementations and factory functions.
+Async registry provider implementations and factory functions.
 """
 
 import os
-from typing import Optional
+import asyncio
+from typing import Optional, Dict, Any
 
 from chuk_tool_processor.registry.interface import ToolRegistryInterface
-from chuk_tool_processor.registry.providers.memory import InMemoryToolRegistry
 
+# Cache for initialized registries
+_REGISTRY_CACHE: Dict[str, ToolRegistryInterface] = {}
+_REGISTRY_LOCKS: Dict[str, asyncio.Lock] = {}
 
-def get_registry(
+
+async def get_registry(
     provider_type: Optional[str] = None, 
     **kwargs
 ) -> ToolRegistryInterface:
     """
-    Factory function to get a registry implementation.
+    Factory function to get a registry implementation asynchronously.
+    
+    This function caches registry instances by provider_type to avoid
+    creating multiple instances unnecessarily. The cache is protected
+    by locks to ensure thread safety.
     
     Args:
         provider_type: Type of registry provider to use. Options:
@@ -34,8 +43,38 @@ def get_registry(
     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}")
+    # Check cache first
+    cache_key = f"{provider_type}:{hash(frozenset(kwargs.items()))}"
+    if cache_key in _REGISTRY_CACHE:
+        return _REGISTRY_CACHE[cache_key]
+    
+    # Create lock if needed
+    if cache_key not in _REGISTRY_LOCKS:
+        _REGISTRY_LOCKS[cache_key] = asyncio.Lock()
+    
+    # Acquire lock to ensure only one registry is created
+    async with _REGISTRY_LOCKS[cache_key]:
+        # Double-check pattern: check cache again after acquiring lock
+        if cache_key in _REGISTRY_CACHE:
+            return _REGISTRY_CACHE[cache_key]
+            
+        # Create the appropriate provider
+        if provider_type == "memory":
+            # Import here to avoid circular imports
+            from chuk_tool_processor.registry.providers.memory import InMemoryToolRegistry
+            registry = InMemoryToolRegistry()
+        else:
+            raise ValueError(f"Unknown registry provider type: {provider_type}")
+        
+        # Cache the registry
+        _REGISTRY_CACHE[cache_key] = registry
+        return registry
+
+
+async def clear_registry_cache() -> None:
+    """
+    Clear the registry cache.
+    
+    This is useful in tests or when configuration changes.
+    """
+    _REGISTRY_CACHE.clear()

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