chuk-tool-processor 0.6.4__py3-none-any.whl → 0.9.7__py3-none-any.whl

chuk_tool_processor/registry/metadata.py

@@ -2,17 +2,19 @@
 """
 Tool metadata models for the registry with async-native support.
 """
+
 from __future__ import annotations
 
-from typing import Any, Dict, Optional, Set, List, Union
 from datetime import datetime
+from typing import Any
+
 from pydantic import BaseModel, Field, model_validator
 
 
 class ToolMetadata(BaseModel):
     """
     Metadata for registered tools.
-    
+
     Attributes:
         name: The name of the tool.
         namespace: The namespace the tool belongs to.
@@ -31,38 +33,39 @@ class ToolMetadata(BaseModel):
         timeout: Optional default timeout in seconds.
         rate_limit: Optional rate limiting configuration.
     """
+
     name: str = Field(..., description="Tool name")
     namespace: str = Field("default", description="Namespace the tool belongs to")
-    description: Optional[str] = Field(None, description="Tool description")
+    description: str | None = Field(None, description="Tool description")
     version: str = Field("1.0.0", description="Tool implementation version")
     is_async: bool = Field(True, description="Whether the tool's execute method is asynchronous")
-    argument_schema: Optional[Dict[str, Any]] = Field(None, description="Schema for the tool's arguments")
-    result_schema: Optional[Dict[str, Any]] = Field(None, description="Schema for the tool's result")
+    argument_schema: dict[str, Any] | None = Field(None, description="Schema for the tool's arguments")
+    result_schema: dict[str, Any] | None = Field(None, description="Schema for the tool's result")
     requires_auth: bool = Field(False, description="Whether the tool requires authentication")
-    tags: Set[str] = Field(default_factory=set, description="Tags associated with the tool")
+    tags: set[str] = Field(default_factory=set, description="Tags associated with the tool")
     created_at: datetime = Field(default_factory=datetime.utcnow, description="When the tool was first registered")
     updated_at: datetime = Field(default_factory=datetime.utcnow, description="When the tool was last updated")
-    source: Optional[str] = Field(None, description="Source of the tool (e.g., 'function', 'class', 'langchain')")
-    source_name: Optional[str] = Field(None, description="Source identifier (e.g., function name, class name)")
-    concurrency_limit: Optional[int] = Field(None, description="Maximum concurrent executions (None = unlimited)")
-    timeout: Optional[float] = Field(None, description="Default timeout in seconds (None = no timeout)")
-    rate_limit: Optional[Dict[str, Any]] = Field(None, description="Rate limiting configuration")
-    
+    source: str | None = Field(None, description="Source of the tool (e.g., 'function', 'class', 'langchain')")
+    source_name: str | None = Field(None, description="Source identifier (e.g., function name, class name)")
+    concurrency_limit: int | None = Field(None, description="Maximum concurrent executions (None = unlimited)")
+    timeout: float | None = Field(None, description="Default timeout in seconds (None = no timeout)")
+    rate_limit: dict[str, Any] | None = Field(None, description="Rate limiting configuration")
+
     # Additional fields for async-native architecture
     supports_streaming: bool = Field(False, description="Whether the tool supports streaming responses")
-    execution_options: Dict[str, Any] = Field(default_factory=dict, description="Additional execution options")
-    dependencies: List[str] = Field(default_factory=list, description="Dependencies on other tools")
-    
-    @model_validator(mode='after')
-    def ensure_async(self) -> 'ToolMetadata':
+    execution_options: dict[str, Any] = Field(default_factory=dict, description="Additional execution options")
+    dependencies: list[str] = Field(default_factory=list, description="Dependencies on other tools")
+
+    @model_validator(mode="after")
+    def ensure_async(self) -> ToolMetadata:
         """Ensure all tools are marked as async in the async-native architecture."""
         self.is_async = True
         return self
-    
-    def with_updated_timestamp(self) -> 'ToolMetadata':
+
+    def with_updated_timestamp(self) -> ToolMetadata:
         """Create a copy with updated timestamp."""
         return self.model_copy(update={"updated_at": datetime.utcnow()})
-    
+
     def __str__(self) -> str:
         """String representation of the tool metadata."""
         return f"{self.namespace}.{self.name} (v{self.version})"
@@ -70,6 +73,7 @@ class ToolMetadata(BaseModel):
 
 class RateLimitConfig(BaseModel):
     """Rate limiting configuration for tools."""
+
     requests: int = Field(..., description="Maximum number of requests")
     period: float = Field(..., description="Time period in seconds")
     scope: str = Field("global", description="Scope of rate limiting: 'global', 'user', 'ip'")
@@ -77,6 +81,7 @@ class RateLimitConfig(BaseModel):
 
 class StreamingToolMetadata(ToolMetadata):
     """Extended metadata for tools that support streaming responses."""
+
     supports_streaming: bool = Field(True, description="Whether the tool supports streaming responses")
-    chunk_size: Optional[int] = Field(None, description="Suggested chunk size for streaming")
-    content_type: Optional[str] = Field(None, description="Content type for streaming responses")
+    chunk_size: int | None = Field(None, description="Suggested chunk size for streaming")
+    content_type: str | None = Field(None, description="Content type for streaming responses")

chuk_tool_processor/registry/provider.py

@@ -4,12 +4,12 @@ Global access to the async tool registry instance.
 
 There are two public faces:
 
-1.  **Module helpers**  
+1.  **Module helpers**
     • `get_registry()` lazily instantiates a default `InMemoryToolRegistry`
-      and memoises it in the module-level variable ``_REGISTRY``.  
+      and memoises it in the module-level variable ``_REGISTRY``.
     • `set_registry()` lets callers replace or reset that singleton.
 
-2.  **`ToolRegistryProvider` class**  
+2.  **`ToolRegistryProvider` class**
     Provides static methods for async-safe access to the registry.
 
 The contract verified by the test-suite is:
@@ -19,12 +19,12 @@ The contract verified by the test-suite is:
 * `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
 
 import asyncio
-import importlib
 import sys
-from typing import Optional, Callable, Awaitable, Dict, Any
+from collections.abc import Awaitable, Callable
 
 # registry
 from .interface import ToolRegistryInterface
@@ -32,7 +32,7 @@ from .interface import ToolRegistryInterface
 # --------------------------------------------------------------------------- #
 # Module-level singleton used by the helper functions
 # --------------------------------------------------------------------------- #
-_REGISTRY: Optional[ToolRegistryInterface] = None
+_REGISTRY: ToolRegistryInterface | None = None
 _REGISTRY_LOCK = asyncio.Lock()
 # --------------------------------------------------------------------------- #
 
@@ -41,13 +41,14 @@ 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()
 
 
 async def get_registry() -> ToolRegistryInterface:
     """
     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.
     """
@@ -79,7 +80,7 @@ class ToolRegistryProvider:
     """Async static wrapper for registry access."""
 
     # Thread-safe singleton management
-    _registry: Optional[ToolRegistryInterface] = None
+    _registry: ToolRegistryInterface | None = None
     _lock = asyncio.Lock()
 
     # ------------------------ public API ------------------------ #
@@ -87,7 +88,7 @@ class ToolRegistryProvider:
     async def get_registry() -> ToolRegistryInterface:
         """
         Return the cached instance or initialize a new one asynchronously.
-        
+
         This method ensures thread-safety when initializing the registry.
         """
         if ToolRegistryProvider._registry is None:
@@ -96,12 +97,10 @@ class ToolRegistryProvider:
                 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"
-                    )
+                    get_registry_func: Callable[[], Awaitable[ToolRegistryInterface]] = module.get_registry
                     # Call it to get the registry
                     ToolRegistryProvider._registry = await get_registry_func()
-        
+
         return ToolRegistryProvider._registry
 
     @staticmethod
@@ -116,23 +115,23 @@ class ToolRegistryProvider:
         """
         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.
         """
-        return await get_registry()
+        return await get_registry()

chuk_tool_processor/registry/providers/__init__.py

@@ -3,38 +3,34 @@
 Async registry provider implementations and factory functions.
 """
 
-import os
 import asyncio
-from typing import Optional, Dict, Any
+import os
 
 from chuk_tool_processor.registry.interface import ToolRegistryInterface
 
 # Cache for initialized registries
-_REGISTRY_CACHE: Dict[str, ToolRegistryInterface] = {}
-_REGISTRY_LOCKS: Dict[str, asyncio.Lock] = {}
+_REGISTRY_CACHE: dict[str, ToolRegistryInterface] = {}
+_REGISTRY_LOCKS: dict[str, asyncio.Lock] = {}
 
 
-async def get_registry(
-    provider_type: Optional[str] = None, 
-    **kwargs
-) -> ToolRegistryInterface:
+async def get_registry(provider_type: str | None = None, **kwargs) -> ToolRegistryInterface:
     """
     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:
             - "memory" (default): In-memory implementation
             - "redis": Redis-backed implementation (if available)
             - "sqlalchemy": Database-backed implementation (if available)
         **kwargs: Additional configuration for the provider.
-    
+
     Returns:
         A registry implementation.
-    
+
     Raises:
         ImportError: If the requested provider is not available.
         ValueError: If the provider type is not recognized.
@@ -42,30 +38,31 @@ async def get_registry(
     # Use environment variable if not specified
     if provider_type is None:
         provider_type = os.environ.get("CHUK_TOOL_REGISTRY_PROVIDER", "memory")
-    
+
     # 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
@@ -74,7 +71,7 @@ async def get_registry(
 async def clear_registry_cache() -> None:
     """
     Clear the registry cache.
-    
+
     This is useful in tests or when configuration changes.
     """
-    _REGISTRY_CACHE.clear()
+    _REGISTRY_CACHE.clear()

chuk_tool_processor/registry/providers/memory.py

@@ -2,11 +2,12 @@
 """
 In-memory implementation of the asynchronous tool registry.
 """
+
 from __future__ import annotations
 
 import asyncio
 import inspect
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any
 
 from chuk_tool_processor.core.exceptions import ToolNotFoundError
 from chuk_tool_processor.registry.interface import ToolRegistryInterface
@@ -27,9 +28,9 @@ class InMemoryToolRegistry(ToolRegistryInterface):
 
     def __init__(self) -> None:
         # {namespace: {tool_name: tool_obj}}
-        self._tools: Dict[str, Dict[str, Any]] = {}
+        self._tools: dict[str, dict[str, Any]] = {}
         # {namespace: {tool_name: ToolMetadata}}
-        self._metadata: Dict[str, Dict[str, ToolMetadata]] = {}
+        self._metadata: dict[str, dict[str, ToolMetadata]] = {}
         # Lock for thread safety
         self._lock = asyncio.Lock()
 
@@ -40,9 +41,9 @@ class InMemoryToolRegistry(ToolRegistryInterface):
     async def register_tool(
         self,
         tool: Any,
-        name: Optional[str] = None,
+        name: str | None = None,
         namespace: str = "default",
-        metadata: Optional[Dict[str, Any]] = None,
+        metadata: dict[str, Any] | None = None,
     ) -> None:
         """Register a tool in the registry asynchronously."""
         async with self._lock:
@@ -57,13 +58,9 @@ class InMemoryToolRegistry(ToolRegistryInterface):
             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
-            )
+            description = (inspect.getdoc(tool) or "").strip() if not (metadata and "description" in metadata) else None
 
-            meta_dict: Dict[str, Any] = {
+            meta_dict: dict[str, Any] = {
                 "name": key,
                 "namespace": namespace,
                 "is_async": is_async,
@@ -79,7 +76,7 @@ class InMemoryToolRegistry(ToolRegistryInterface):
     # retrieval
     # ------------------------------------------------------------------ #
 
-    async def get_tool(self, name: str, namespace: str = "default") -> Optional[Any]:
+    async def get_tool(self, name: str, namespace: str = "default") -> Any | None:
         """Retrieve a tool by name and namespace asynchronously."""
         # Read operations don't need locking for better concurrency
         return self._tools.get(namespace, {}).get(name)
@@ -91,9 +88,7 @@ class InMemoryToolRegistry(ToolRegistryInterface):
             raise ToolNotFoundError(f"{namespace}.{name}")
         return tool
 
-    async def get_metadata(
-        self, name: str, namespace: str = "default"
-    ) -> Optional[ToolMetadata]:
+    async def get_metadata(self, name: str, namespace: str = "default") -> ToolMetadata | None:
         """Get metadata for a tool asynchronously."""
         return self._metadata.get(namespace, {}).get(name)
 
@@ -101,25 +96,23 @@ class InMemoryToolRegistry(ToolRegistryInterface):
     # listing helpers
     # ------------------------------------------------------------------ #
 
-    async def list_tools(self, namespace: Optional[str] = None) -> List[Tuple[str, str]]:
+    async def list_tools(self, namespace: str | None = None) -> list[tuple[str, str]]:
         """
         Return a list of ``(namespace, name)`` tuples asynchronously.
         """
         if namespace:
-            return [
-                (namespace, n) for n in self._tools.get(namespace, {}).keys()
-            ]
+            return [(namespace, n) for n in self._tools.get(namespace, {})]
 
-        result: List[Tuple[str, str]] = []
+        result: list[tuple[str, str]] = []
         for ns, tools in self._tools.items():
-            result.extend((ns, n) for n in tools.keys())
+            result.extend((ns, n) for n in tools)
         return result
 
-    async def list_namespaces(self) -> List[str]:
+    async def list_namespaces(self) -> list[str]:
         """List all namespaces asynchronously."""
         return list(self._tools.keys())
 
-    async def list_metadata(self, namespace: Optional[str] = None) -> List[ToolMetadata]:
+    async def list_metadata(self, namespace: str | None = None) -> list[ToolMetadata]:
         """
         Return all ToolMetadata objects asynchronously.
 
@@ -135,7 +128,7 @@ class InMemoryToolRegistry(ToolRegistryInterface):
             return list(self._metadata.get(namespace, {}).values())
 
         # flatten
-        result: List[ToolMetadata] = []
+        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

@@ -3,10 +3,11 @@
 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
 
 import asyncio
-from typing import Dict, List, Any, Optional, Mapping
+from typing import Any
 
 # registry
 from .provider import ToolRegistryProvider
@@ -14,19 +15,19 @@ from .provider import ToolRegistryProvider
 # --------------------------------------------------------------------------- #
 # internal cache so tool-name lookup is O(1) with async protection
 # --------------------------------------------------------------------------- #
-_OPENAI_NAME_CACHE: Optional[Dict[str, Any]] = None
+_OPENAI_NAME_CACHE: dict[str, Any] | None = None
 _CACHE_LOCK = asyncio.Lock()
 
 
 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
-    
+
     # Fast path - cache already exists
     if _OPENAI_NAME_CACHE is not None:
         return
@@ -36,16 +37,16 @@ async def _build_openai_name_cache() -> None:
         # 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)
@@ -71,7 +72,7 @@ async def _build_openai_name_cache() -> None:
 # --------------------------------------------------------------------------- #
 # public helpers
 # --------------------------------------------------------------------------- #
-async 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.
@@ -79,23 +80,23 @@ async 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
     """
     # Get the registry
     reg = await ToolRegistryProvider.get_registry()
-    specs: List[Dict[str, Any]] = []
+    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()
@@ -117,21 +118,21 @@ async def tool_by_openai_name(name: str) -> Any:
 
     Args:
         name: The OpenAI function name
-        
+
     Returns:
         The tool implementation
-        
+
     Raises:
         KeyError: If the name is unknown
     """
     # Ensure the cache is built
     await _build_openai_name_cache()
-    
+
     # Look up the tool
     try:
         if _OPENAI_NAME_CACHE is None:
-            raise KeyError(f"Tool cache not initialized")
-            
+            raise KeyError("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
@@ -140,7 +141,7 @@ async def tool_by_openai_name(name: str) -> Any:
 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
@@ -152,51 +153,51 @@ async def export_tools_as_openapi(
     title: str = "Tool API",
     version: str = "1.0.0",
     description: str = "API for registered tools",
-) -> Dict[str, Any]:
+) -> 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] = {}
-    
+    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": {
@@ -209,7 +210,7 @@ async def export_tools_as_openapi(
                         "application/json": {
                             "schema": {"$ref": f"#/components/schemas/{key}Args"} if arg_schema else {}
                         }
-                    }
+                    },
                 },
                 "responses": {
                     "200": {
@@ -218,28 +219,18 @@ async def export_tools_as_openapi(
                             "application/json": {
                                 "schema": {"$ref": f"#/components/schemas/{key}Result"} if result_schema else {}
                             }
-                        }
-                    },
-                    "400": {
-                        "description": "Bad request"
+                        },
                     },
-                    "500": {
-                        "description": "Internal server error"
-                    }
-                }
+                    "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
-        },
+        "info": {"title": title, "version": version, "description": description},
         "paths": paths,
-        "components": {
-            "schemas": schemas
-        }
-    }
+        "components": {"schemas": schemas},
+    }