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

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(),
+        )

chuk_tool_processor/registry/decorators.py

@@ -1,24 +1,42 @@
 # chuk_tool_processor/registry/decorators.py
 """
-Decorators for registering tools with the registry.
+Decorators for registering tools with the registry asynchronously.
 """
 
-from functools import wraps
-from typing import Any, Callable, Dict, Optional, Type, TypeVar
+import asyncio
+import functools
+import inspect
+import sys
+import weakref
+import atexit
+import warnings
+from typing import Any, Callable, Dict, Optional, Type, TypeVar, cast, Set, List, Awaitable
 
 from chuk_tool_processor.registry.provider import ToolRegistryProvider
 
 T = TypeVar('T')
 
+# Global tracking of classes to be registered
+# Store coroutines rather than awaitables to avoid warnings
+_PENDING_REGISTRATIONS: List[Callable[[], Awaitable]] = []
+_REGISTERED_CLASSES = weakref.WeakSet()
+
+# Keep track of whether we're shutting down
+_SHUTTING_DOWN = False
+
 
 def register_tool(name: Optional[str] = None, namespace: str = "default", **metadata):
     """
     Decorator for registering tools with the global registry.
     
+    This decorator will queue the registration to happen asynchronously.
+    You must call `await ensure_registrations()` in your application startup
+    to complete all registrations.
+    
     Example:
         @register_tool(name="my_tool", namespace="math", description="Performs math operations")
         class MyTool:
-            def execute(self, x: int, y: int) -> int:
+            async def execute(self, x: int, y: int) -> int:
                 return x + y
     
     Args:
@@ -30,13 +48,118 @@ def register_tool(name: Optional[str] = None, namespace: str = "default", **meta
         A decorator function that registers the class with the registry.
     """
     def decorator(cls: Type[T]) -> Type[T]:
-        registry = ToolRegistryProvider.get_registry()
-        registry.register_tool(cls, name=name, namespace=namespace, metadata=metadata)
+        # Skip if already registered
+        if cls in _REGISTERED_CLASSES:
+            return cls
+            
+        # Skip if shutting down
+        if _SHUTTING_DOWN:
+            return cls
+
+        # Ensure execute method is async
+        if hasattr(cls, 'execute') and not inspect.iscoroutinefunction(cls.execute):
+            raise TypeError(f"Tool {cls.__name__} must have an async execute method")
+            
+        # Create registration function (not coroutine)
+        async def do_register():
+            registry = await ToolRegistryProvider.get_registry()
+            await registry.register_tool(
+                cls, 
+                name=name, 
+                namespace=namespace, 
+                metadata=metadata
+            )
         
-        @wraps(cls)
-        def wrapper(*args: Any, **kwargs: Dict[str, Any]) -> T:
-            return cls(*args, **kwargs)
+        # Store the function, not the coroutine
+        _PENDING_REGISTRATIONS.append(do_register)
+        _REGISTERED_CLASSES.add(cls)
+        
+        # Add class attribute so we can identify decorated classes
+        cls._tool_registration_info = {
+            'name': name or cls.__name__,
+            'namespace': namespace,
+            'metadata': metadata
+        }
+        
+        # Don't modify the original class
+        return cls
+    
+    return decorator
+
+
+async def ensure_registrations() -> None:
+    """
+    Process all pending tool registrations.
+    
+    This must be called during application startup to register
+    all tools decorated with @register_tool.
+    
+    Returns:
+        None
+    """
+    global _PENDING_REGISTRATIONS
+    
+    if not _PENDING_REGISTRATIONS:
+        return
         
-        return wrapper
+    # Create tasks from the stored functions
+    tasks = []
+    for registration_fn in _PENDING_REGISTRATIONS:
+        # Now we await the function to get the coroutine, then create a task
+        tasks.append(asyncio.create_task(registration_fn()))
+    
+    # Clear the pending list
+    _PENDING_REGISTRATIONS.clear()
     
-    return decorator
+    # Wait for all registrations to complete
+    if tasks:
+        await asyncio.gather(*tasks)
+
+
+def discover_decorated_tools() -> List[Type]:
+    """
+    Discover all tool classes decorated with @register_tool.
+    
+    This can be used to inspect what tools have been registered
+    without awaiting ensure_registrations().
+    
+    Returns:
+        List of tool classes that have been decorated
+    """
+    tools = []
+    
+    # Search all loaded modules
+    for module_name, module in list(sys.modules.items()):
+        if not module_name.startswith('chuk_tool_processor'):
+            continue
+            
+        for attr_name in dir(module):
+            try:
+                attr = getattr(module, attr_name)
+                if hasattr(attr, '_tool_registration_info'):
+                    tools.append(attr)
+            except (AttributeError, ImportError):
+                pass
+                
+    return tools
+
+
+# Register atexit handler to prevent warnings at shutdown
+def _handle_shutdown():
+    """
+    Handle shutdown by marking shutdown flag and clearing pending registrations.
+    This prevents warnings about unawaited coroutines.
+    """
+    global _SHUTTING_DOWN, _PENDING_REGISTRATIONS
+    
+    # Set the shutdown flag
+    _SHUTTING_DOWN = True
+    
+    # Clear without creating any coroutines
+    _PENDING_REGISTRATIONS = []
+
+# Register the shutdown handler
+atexit.register(_handle_shutdown)
+
+# Filter the coroutine never awaited warning
+warnings.filterwarnings("ignore", message="coroutine.*was never awaited")

chuk_tool_processor/registry/interface.py

@@ -1,19 +1,23 @@
 # chuk_tool_processor/registry/interface.py
 """
-Defines the interface for tool registries.
+Defines the interface for asynchronous tool registries.
 """
-from typing import Protocol, Any, Dict, List, Optional, Tuple
+from __future__ import annotations
 
-# imports
+from typing import Protocol, Any, Dict, List, Optional, Tuple, TypeVar, runtime_checkable
+
+# imports
 from chuk_tool_processor.registry.metadata import ToolMetadata
 
+T = TypeVar('T')
 
+@runtime_checkable
 class ToolRegistryInterface(Protocol):
     """
-    Protocol for a tool registry. Implementations should allow registering tools
+    Protocol for an async tool registry. Implementations should allow registering tools
     and retrieving them by name and namespace.
     """
-    def register_tool(
+    async def register_tool(
         self, 
         tool: Any, 
         name: Optional[str] = None,
@@ -21,7 +25,7 @@ class ToolRegistryInterface(Protocol):
         metadata: Optional[Dict[str, Any]] = None
     ) -> None:
         """
-        Register a tool implementation.
+        Register a tool implementation asynchronously.
 
         Args:
             tool: The tool class or instance with an `execute` method.
@@ -31,9 +35,9 @@ class ToolRegistryInterface(Protocol):
         """
         ...
 
-    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 registered tool by name and namespace.
+        Retrieve a registered tool by name and namespace asynchronously.
         
         Args:
             name: The name of the tool.
@@ -44,9 +48,25 @@ class ToolRegistryInterface(Protocol):
         """
         ...
 
-    def get_metadata(self, name: str, namespace: str = "default") -> Optional[ToolMetadata]:
+    async def get_tool_strict(self, name: str, namespace: str = "default") -> Any:
+        """
+        Retrieve a registered tool by name and namespace, raising 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 in the registry.
+        """
+        ...
+
+    async def get_metadata(self, name: str, namespace: str = "default") -> Optional[ToolMetadata]:
         """
-        Retrieve metadata for a registered tool.
+        Retrieve metadata for a registered tool asynchronously.
         
         Args:
             name: The name of the tool.
@@ -57,9 +77,9 @@ class ToolRegistryInterface(Protocol):
         """
         ...
 
-    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]]:
         """
-        List all registered tool names, optionally filtered by namespace.
+        List all registered tool names asynchronously, optionally filtered by namespace.
         
         Args:
             namespace: Optional namespace filter.
@@ -69,11 +89,25 @@ class ToolRegistryInterface(Protocol):
         """
         ...
 
-    def list_namespaces(self) -> List[str]:
+    async def list_namespaces(self) -> List[str]:
         """
-        List all registered namespaces.
+        List all registered namespaces asynchronously.
         
         Returns:
             List of namespace names.
         """
+        ...
+        
+    async def list_metadata(self, namespace: Optional[str] = None) -> List[ToolMetadata]:
+        """
+        Return all ToolMetadata objects asynchronously.
+
+        Args:
+            namespace: Optional filter by namespace.
+                • None (default) – metadata from all namespaces
+                • "some_ns" – only that namespace
+
+        Returns:
+            List of ToolMetadata objects.
+        """
         ...

chuk_tool_processor/registry/metadata.py

@@ -1,9 +1,12 @@
 # chuk_tool_processor/registry/metadata.py
 """
-Tool metadata models for the registry.
+Tool metadata models for the registry with async-native support.
 """
-from typing import Any, Dict, Optional, Set
-from pydantic import BaseModel, Field
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Set, List, Union
+from datetime import datetime
+from pydantic import BaseModel, Field, model_validator
 
 
 class ToolMetadata(BaseModel):
@@ -20,17 +23,60 @@ class ToolMetadata(BaseModel):
         result_schema: Optional schema for the tool's result.
         requires_auth: Whether the tool requires authentication.
         tags: Set of tags associated with the tool.
+        created_at: When the tool was first registered.
+        updated_at: When the tool was last updated.
+        source: Optional source information (e.g., "function", "class", "langchain").
+        source_name: Optional source identifier.
+        concurrency_limit: Optional maximum concurrent executions.
+        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")
     version: str = Field("1.0.0", description="Tool implementation version")
-    is_async: bool = Field(False, description="Whether the tool's execute method is asynchronous")
+    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")
     requires_auth: bool = Field(False, description="Whether the tool requires authentication")
     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")
+    
+    # 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':
+        """Ensure all tools are marked as async in the async-native architecture."""
+        self.is_async = True
+        return self
+    
+    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})"
+        return f"{self.namespace}.{self.name} (v{self.version})"
+
+
+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'")
+
+
+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")