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

chuk_tool_processor/logging/metrics.py

@@ -1,25 +1,52 @@
 # chuk_tool_processor/logging/metrics.py
+"""
+Metrics logging for tool execution.
+"""
 from __future__ import annotations
+
+import asyncio
+from typing import Dict, Any, Optional
+
+# Import directly from context to avoid circular imports
 from .context import get_logger
 
 __all__ = ["metrics", "MetricsLogger"]
 
 
 class MetricsLogger:
+    """
+    Logger for collecting and reporting metrics about tool execution.
+    
+    Provides methods to log tool execution metrics and parser metrics
+    in a structured format.
+    """
+    
     def __init__(self):
+        """Initialize with logger."""
         self.logger = get_logger("chuk_tool_processor.metrics")
 
     # ------------------------------------------------------------------
-    def log_tool_execution(
+    async def log_tool_execution(
         self,
         tool: str,
         success: bool,
         duration: float,
         *,
-        error: str | None = None,
+        error: Optional[str] = None,
         cached: bool = False,
         attempts: int = 1,
-    ):
+    ) -> None:
+        """
+        Log metrics for a tool execution.
+        
+        Args:
+            tool: Name of the tool
+            success: Whether execution was successful
+            duration: Execution duration in seconds
+            error: Optional error message if execution failed
+            cached: Whether the result was retrieved from cache
+            attempts: Number of execution attempts
+        """
         self.logger.info(
             f"Tool execution metric: {tool}",
             extra={
@@ -35,13 +62,22 @@ class MetricsLogger:
             },
         )
 
-    def log_parser_metric(
+    async def log_parser_metric(
         self,
         parser: str,
         success: bool,
         duration: float,
         num_calls: int,
-    ):
+    ) -> None:
+        """
+        Log metrics for a parser.
+        
+        Args:
+            parser: Name of the parser
+            success: Whether parsing was successful
+            duration: Parsing duration in seconds
+            num_calls: Number of tool calls parsed
+        """
         self.logger.info(
             f"Parser metric: {parser}",
             extra={
@@ -54,6 +90,39 @@ class MetricsLogger:
                 }
             },
         )
+        
+    async def log_registry_metric(
+        self,
+        operation: str,
+        success: bool,
+        duration: float,
+        tool: Optional[str] = None,
+        namespace: Optional[str] = None,
+    ) -> None:
+        """
+        Log metrics for registry operations.
+        
+        Args:
+            operation: Type of registry operation
+            success: Whether operation was successful
+            duration: Operation duration in seconds
+            tool: Optional tool name
+            namespace: Optional namespace
+        """
+        self.logger.info(
+            f"Registry metric: {operation}",
+            extra={
+                "context": {
+                    "metric_type": "registry",
+                    "operation": operation,
+                    "success": success,
+                    "duration": duration,
+                    "tool": tool,
+                    "namespace": namespace,
+                }
+            },
+        )
 
 
-metrics = MetricsLogger()
+# Create global instance
+metrics = MetricsLogger()

chuk_tool_processor/mcp/mcp_tool.py

@@ -1,53 +1,98 @@
+#!/usr/bin/env python
 # chuk_tool_processor/mcp/mcp_tool.py
 """
-MCP tool that uses StreamManager for execution.
+MCP tool shim that delegates execution to a StreamManager,
+handling its own lazy bootstrap when needed.
 """
+from __future__ import annotations
 
-from typing import Any
+import asyncio
+from typing import Any, Dict, List, Optional
 
-from chuk_tool_processor.mcp.stream_manager import StreamManager
 from chuk_tool_processor.logging import get_logger
+from chuk_tool_processor.mcp.stream_manager import StreamManager
 
 logger = get_logger("chuk_tool_processor.mcp.mcp_tool")
 
+
 class MCPTool:
     """
-    MCP tool that uses StreamManager for execution.
-    
-    This tool handles both namespaced and non-namespaced execution.
+    Wrap a remote MCP tool so it can be called like a local tool.
+
+    You may pass an existing ``StreamManager`` *positionally* (for legacy
+    code) or via the named parameter.
+
+    If no ``StreamManager`` is supplied the class will start one on first
+    use via ``setup_mcp_stdio``.
     """
-    
-    def __init__(self, tool_name: str, stream_manager: StreamManager):
+
+    # ------------------------------------------------------------------ #
+    def __init__(
+        self,
+        tool_name: str,
+        stream_manager: Optional[StreamManager] = None,
+        *,
+        cfg_file: str = "",
+        servers: Optional[List[str]] = None,
+        server_names: Optional[Dict[int, str]] = None,
+        namespace: str = "stdio",
+    ) -> None:
+        self.tool_name = tool_name
+        self._sm: Optional[StreamManager] = stream_manager
+
+        # Boot-strap parameters (only needed if _sm is None)
+        self._cfg_file = cfg_file
+        self._servers = servers or []
+        self._server_names = server_names or {}
+        self._namespace = namespace
+
+        self._sm_lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------ #
+    async def _ensure_stream_manager(self) -> StreamManager:
         """
-        Initialize the MCP tool.
-        
-        Args:
-            tool_name: Name of the MCP tool
-            stream_manager: StreamManager instance
+        Lazily create / attach a StreamManager.
+
+        Importing ``setup_mcp_stdio`` *inside* this function prevents the
+        circular-import seen earlier.  ★
         """
-        self.tool_name = tool_name
-        self.stream_manager = stream_manager
-        
+        if self._sm is not None:
+            return self._sm
+
+        async with self._sm_lock:
+            if self._sm is None:  # re-check inside lock
+                logger.info(
+                    "Boot-strapping MCP stdio transport for '%s'", self.tool_name
+                )
+
+                # ★  local import avoids circular dependency
+                from chuk_tool_processor.mcp.setup_mcp_stdio import setup_mcp_stdio
+
+                _, self._sm = await setup_mcp_stdio(
+                    config_file=self._cfg_file,
+                    servers=self._servers,
+                    server_names=self._server_names,
+                    namespace=self._namespace,
+                )
+
+        return self._sm  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------ #
     async def execute(self, **kwargs: Any) -> Any:
         """
-        Execute the tool using StreamManager.
-        
-        Args:
-            **kwargs: Tool arguments
-            
-        Returns:
-            Tool result
+        Forward the call to the remote MCP tool.
+
+        Raises
+        ------
+        RuntimeError
+            If the server returns an error payload.
         """
-        logger.debug(f"Executing MCP tool {self.tool_name}")
-        
-        result = await self.stream_manager.call_tool(
-            tool_name=self.tool_name,
-            arguments=kwargs
-        )
-        
+        sm = await self._ensure_stream_manager()
+        result = await sm.call_tool(tool_name=self.tool_name, arguments=kwargs)
+
         if result.get("isError"):
-            error_msg = result.get("error", "Unknown error")
-            logger.error(f"Error executing MCP tool {self.tool_name}: {error_msg}")
-            raise RuntimeError(error_msg)
-            
-        return result.get("content")
+            err = result.get("error", "Unknown error")
+            logger.error("Remote MCP error from '%s': %s", self.tool_name, err)
+            raise RuntimeError(err)
+
+        return result.get("content")

chuk_tool_processor/mcp/register_mcp_tools.py

@@ -1,82 +1,100 @@
+#!/usr/bin/env python
 # chuk_tool_processor/mcp/register_mcp_tools.py
 """
-Registration functions for MCP tools.
+Discover the remote MCP tools exposed by a :class:`~chuk_tool_processor.mcp.stream_manager.StreamManager`
+instance and register them in the local CHUK registry.
+
+The helper is now **async-native** – call it with ``await``.
 """
 
-from typing import List, Dict, Any
+from __future__ import annotations
+
+from typing import Any, Dict, List
 
+from chuk_tool_processor.logging import get_logger
 from chuk_tool_processor.mcp.mcp_tool import MCPTool
 from chuk_tool_processor.mcp.stream_manager import StreamManager
 from chuk_tool_processor.registry.provider import ToolRegistryProvider
-from chuk_tool_processor.logging import get_logger
 
 logger = get_logger("chuk_tool_processor.mcp.register")
 
 
-def register_mcp_tools(
+# --------------------------------------------------------------------------- #
+# public API
+# --------------------------------------------------------------------------- #
+async def register_mcp_tools(
     stream_manager: StreamManager,
-    namespace: str = "mcp"
+    namespace: str = "mcp",
 ) -> List[str]:
     """
-    Register MCP tools with the CHUK registry.
-    
-    Args:
-        stream_manager: StreamManager instance
-        namespace: Namespace for the tools
-        
-    Returns:
-        List of registered tool names
+    Pull the *remote* tool catalogue from *stream_manager* and create a local
+    async wrapper (:class:`MCPTool`) for each entry.
+
+    Parameters
+    ----------
+    stream_manager
+        An **initialised** :class:`~chuk_tool_processor.mcp.stream_manager.StreamManager`.
+    namespace
+        All tools are registered twice:
+
+        * under their original name in *namespace* (e.g. ``"mcp.echo"``), and
+        * mirrored into the ``"default"`` namespace as ``"{namespace}.{name}"``
+          so that parsers may reference them unambiguously.
+
+    Returns
+    -------
+    list[str]
+        The *plain* tool names that were registered (duplicates are ignored).
     """
-    registry = ToolRegistryProvider.get_registry()
-    registered_tools = []
-    
-    # Get all tools from StreamManager
-    mcp_tools = stream_manager.get_all_tools()
-    
+    registry = await ToolRegistryProvider.get_registry()
+    registered: List[str] = []
+
+    # 1️⃣  ask the stream-manager for its catalogue
+    mcp_tools: List[Dict[str, Any]] = stream_manager.get_all_tools()
+
     for tool_def in mcp_tools:
         tool_name = tool_def.get("name")
         if not tool_name:
-            logger.warning("Tool definition missing name")
+            logger.warning("Remote tool definition without a 'name' field – skipped")
             continue
-            
-        description = tool_def.get("description", f"MCP tool: {tool_name}")
-        
+
+        description = tool_def.get("description") or f"MCP tool • {tool_name}"
+        meta: Dict[str, Any] = {
+            "description": description,
+            "is_async": True,
+            "tags": {"mcp", "remote"},
+            "argument_schema": tool_def.get("inputSchema", {}),
+        }
+
         try:
-            # Create tool
-            tool = MCPTool(tool_name, stream_manager)
-            
-            # Register with registry under the original name in the given namespace
-            registry.register_tool(
-                tool,
+            wrapper = MCPTool(tool_name, stream_manager)
+
+            # ── primary registration ──────────────────────────────────────
+            await registry.register_tool(
+                wrapper,
                 name=tool_name,
                 namespace=namespace,
-                metadata={
-                    "description": description,
-                    "is_async": True,
-                    "tags": {"mcp", "remote"},
-                    "argument_schema": tool_def.get("inputSchema", {})
-                }
+                metadata=meta,
             )
-            
-            # Also register the tool in the default namespace with the namespaced name
-            # This allows calling the tool as either "echo" or "stdio.echo" from parsers
-            namespaced_tool_name = f"{namespace}.{tool_name}"
-            registry.register_tool(
-                tool,
-                name=namespaced_tool_name,
+
+            # ── mirror into "default" namespace with dotted name ──────────
+            dotted_name = f"{namespace}.{tool_name}"
+            await registry.register_tool(
+                wrapper,
+                name=dotted_name,
                 namespace="default",
-                metadata={
-                    "description": description,
-                    "is_async": True,
-                    "tags": {"mcp", "remote", "namespaced"},
-                    "argument_schema": tool_def.get("inputSchema", {})
-                }
+                metadata={**meta, "tags": meta["tags"] | {"namespaced"}},
+            )
+
+            registered.append(tool_name)
+            logger.debug(
+                "MCP tool '%s' registered (as '%s' & '%s')",
+                tool_name,
+                f"{namespace}:{tool_name}",
+                f"default:{dotted_name}",
             )
-            
-            registered_tools.append(tool_name)
-            logger.info(f"Registered MCP tool '{tool_name}' in namespace '{namespace}' (also as '{namespaced_tool_name}' in default)")
-            
-        except Exception as e:
-            logger.error(f"Error registering MCP tool '{tool_name}': {e}")
-    
-    return registered_tools
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Failed to register MCP tool '%s': %s", tool_name, exc)
+
+    logger.info("MCP registration complete – %d tool(s) available", len(registered))
+    return registered

chuk_tool_processor/mcp/setup_mcp_sse.py

@@ -1,20 +1,34 @@
+#!/usr/bin/env python
 # chuk_tool_processor/mcp/setup_mcp_sse.py
 """
-Setup function for SSE transport MCP integration.
+Utility that wires up:
+
+1. A :class:`~chuk_tool_processor.mcp.stream_manager.StreamManager`
+   using the SSE transport.
+2. The remote MCP tools exposed by that manager (via
+   :pyfunc:`~chuk_tool_processor.mcp.register_mcp_tools.register_mcp_tools`).
+3. A fully-featured :class:`~chuk_tool_processor.core.processor.ToolProcessor`
+   instance that can execute those tools – with optional caching,
+   rate-limiting, retries, etc.
 """
+
 from __future__ import annotations
 
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Tuple
 
 from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.mcp.stream_manager import StreamManager
-from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
 from chuk_tool_processor.logging import get_logger
+from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
+from chuk_tool_processor.mcp.stream_manager import StreamManager
 
 logger = get_logger("chuk_tool_processor.mcp.setup_sse")
 
 
-async def setup_mcp_sse(
+# --------------------------------------------------------------------------- #
+# public helper
+# --------------------------------------------------------------------------- #
+async def setup_mcp_sse(  # noqa: C901 – long, but just a config wrapper
+    *,
     servers: List[Dict[str, str]],
     server_names: Optional[Dict[int, str]] = None,
     default_timeout: float = 10.0,
@@ -26,38 +40,24 @@ async def setup_mcp_sse(
     tool_rate_limits: Optional[Dict[str, tuple]] = None,
     enable_retries: bool = True,
     max_retries: int = 3,
-    namespace: str = "mcp"
-) -> tuple[ToolProcessor, StreamManager]:
+    namespace: str = "mcp",
+) -> Tuple[ToolProcessor, StreamManager]:
     """
-    Set up MCP with SSE transport and CHUK Tool Processor.
-    
-    Args:
-        servers: List of server configurations with "name" and "url" keys
-        server_names: Optional mapping of server indices to names
-        default_timeout: Default timeout for tool execution
-        max_concurrency: Maximum concurrent executions
-        enable_caching: Whether to enable caching
-        cache_ttl: Cache TTL in seconds
-        enable_rate_limiting: Whether to enable rate limiting
-        global_rate_limit: Global rate limit (requests per minute)
-        tool_rate_limits: Per-tool rate limits
-        enable_retries: Whether to enable retries
-        max_retries: Maximum retry attempts
-        namespace: Namespace for MCP tools
-        
-    Returns:
-        Tuple of (processor, stream_manager)
+    Spin up an SSE-backed *StreamManager*, register all its remote tools,
+    and return a ready-to-go :class:`ToolProcessor`.
+
+    Everything is **async-native** – call with ``await``.
     """
-    # Create and initialize StreamManager with SSE transport
+    # 1️⃣  connect to the remote MCP servers
     stream_manager = await StreamManager.create_with_sse(
         servers=servers,
-        server_names=server_names
+        server_names=server_names,
     )
-    
-    # Register MCP tools
-    registered_tools = register_mcp_tools(stream_manager, namespace)
-    
-    # Create processor
+
+    # 2️⃣  introspect & register their tools in the local registry
+    registered = await register_mcp_tools(stream_manager, namespace=namespace)
+
+    # 3️⃣  build a processor configured to your liking
     processor = ToolProcessor(
         default_timeout=default_timeout,
         max_concurrency=max_concurrency,
@@ -67,8 +67,13 @@ async def setup_mcp_sse(
         global_rate_limit=global_rate_limit,
         tool_rate_limits=tool_rate_limits,
         enable_retries=enable_retries,
-        max_retries=max_retries
+        max_retries=max_retries,
+    )
+
+    logger.info(
+        "MCP (SSE) initialised – %s tool%s registered into namespace '%s'",
+        len(registered),
+        "" if len(registered) == 1 else "s",
+        namespace,
     )
-    
-    logger.info(f"Set up MCP (SSE) with {len(registered_tools)} tools")
-    return processor, stream_manager
+    return processor, stream_manager

chuk_tool_processor/mcp/setup_mcp_stdio.py

@@ -1,20 +1,33 @@
+#!/usr/bin/env python
 # chuk_tool_processor/mcp/setup_mcp_stdio.py
 """
-Setup function for stdio transport MCP integration.
+Bootstrap helper for MCP over **stdio** transport.
+
+It:
+
+1. spins up :class:`~chuk_tool_processor.mcp.stream_manager.StreamManager`
+   with the `"stdio"` transport,
+2. discovers & registers the remote MCP tools locally, and
+3. returns a ready-to-use :class:`~chuk_tool_processor.core.processor.ToolProcessor`.
 """
+
 from __future__ import annotations
 
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Tuple
 
 from chuk_tool_processor.core.processor import ToolProcessor
-from chuk_tool_processor.mcp.stream_manager import StreamManager
-from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
 from chuk_tool_processor.logging import get_logger
+from chuk_tool_processor.mcp.register_mcp_tools import register_mcp_tools
+from chuk_tool_processor.mcp.stream_manager import StreamManager
 
 logger = get_logger("chuk_tool_processor.mcp.setup_stdio")
 
 
-async def setup_mcp_stdio(
+# --------------------------------------------------------------------------- #
+# public helper
+# --------------------------------------------------------------------------- #
+async def setup_mcp_stdio(  # noqa: C901 – long but just a config facade
+    *,
     config_file: str,
     servers: List[str],
     server_names: Optional[Dict[int, str]] = None,
@@ -27,41 +40,25 @@ async def setup_mcp_stdio(
     tool_rate_limits: Optional[Dict[str, tuple]] = None,
     enable_retries: bool = True,
     max_retries: int = 3,
-    namespace: str = "mcp"
-) -> tuple[ToolProcessor, StreamManager]:
+    namespace: str = "mcp",
+) -> Tuple[ToolProcessor, StreamManager]:
     """
-    Set up MCP with stdio transport and CHUK Tool Processor.
-    
-    Args:
-        config_file: Path to the config file
-        servers: List of server names to connect to
-        server_names: Optional mapping of server indices to names
-        default_timeout: Default timeout for tool execution
-        max_concurrency: Maximum concurrent executions
-        enable_caching: Whether to enable caching
-        cache_ttl: Cache TTL in seconds
-        enable_rate_limiting: Whether to enable rate limiting
-        global_rate_limit: Global rate limit (requests per minute)
-        tool_rate_limits: Per-tool rate limits
-        enable_retries: Whether to enable retries
-        max_retries: Maximum retry attempts
-        namespace: Namespace for MCP tools
-        
-    Returns:
-        Tuple of (processor, stream_manager)
+    Initialise stdio-transport MCP + a :class:`ToolProcessor`.
+
+    Call with ``await`` from your async context.
     """
-    # Create and initialize StreamManager with stdio transport
+    # 1️⃣  create & connect the stream-manager
     stream_manager = await StreamManager.create(
         config_file=config_file,
         servers=servers,
         server_names=server_names,
-        transport_type="stdio"
+        transport_type="stdio",
     )
-    
-    # Register MCP tools
-    registered_tools = register_mcp_tools(stream_manager, namespace)
-    
-    # Create processor
+
+    # 2️⃣  pull the remote tool list and register each one locally
+    registered = await register_mcp_tools(stream_manager, namespace=namespace)
+
+    # 3️⃣  build a processor instance configured to your taste
     processor = ToolProcessor(
         default_timeout=default_timeout,
         max_concurrency=max_concurrency,
@@ -71,8 +68,13 @@ async def setup_mcp_stdio(
         global_rate_limit=global_rate_limit,
         tool_rate_limits=tool_rate_limits,
         enable_retries=enable_retries,
-        max_retries=max_retries
+        max_retries=max_retries,
+    )
+
+    logger.info(
+        "MCP (stdio) initialised – %s tool%s registered into namespace '%s'",
+        len(registered),
+        "" if len(registered) == 1 else "s",
+        namespace,
     )
-    
-    logger.info(f"Set up MCP (stdio) with {len(registered_tools)} tools")
-    return processor, stream_manager
+    return processor, stream_manager