data-designer-engine 0.4.0rc2__py3-none-any.whl → 0.5.0rc1__py3-none-any.whl

data_designer/engine/mcp/io.py

@@ -0,0 +1,487 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Low-level MCP I/O operations with caching and session pooling.
+
+This module provides stateless functions for MCP communication using an actor-style
+service that owns all async state within a single background event loop. Public APIs
+are synchronous wrappers that submit coroutines to the loop and wait for results.
+
+Architecture:
+    All MCP I/O is funneled through a single dedicated asyncio event loop running
+    in a background daemon thread. This avoids the complexity of managing multiple
+    event loops and allows sessions to be reused across calls from any thread.
+
+    Worker Thread 1 ──┐
+    Worker Thread 2 ──┼──► MCP Event Loop Thread ──► MCP Servers
+    Worker Thread N ──┘    (all sessions live here)
+
+Request Coalescing:
+    When multiple threads request tools from the same provider simultaneously,
+    only one request is made to the MCP server. Other callers wait for the
+    in-flight request to complete and share the result. This prevents N
+    concurrent workers from making N separate ListToolsRequest calls.
+
+The caller (MCPFacade) is responsible for resolving any secret references in
+provider api_key fields before passing providers to these functions.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import json
+import logging
+import threading
+from collections.abc import Coroutine, Iterable
+from typing import Any
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.sse import sse_client
+from mcp.client.stdio import stdio_client
+
+from data_designer.config.mcp import LocalStdioMCPProvider, MCPProviderT
+from data_designer.engine.mcp.errors import MCPToolError
+from data_designer.engine.mcp.registry import MCPToolDefinition, MCPToolResult
+
+logger = logging.getLogger(__name__)
+
+
+def _provider_cache_key(provider: MCPProviderT) -> str:
+    """Create a stable cache key for a provider."""
+    data = provider.model_dump(mode="json")
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+class MCPIOService:
+    """Actor-style MCP I/O service owning all async state."""
+
+    def __init__(self) -> None:
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._loop_lock = threading.Lock()
+
+        self._sessions: dict[str, ClientSession] = {}
+        self._session_contexts: dict[str, Any] = {}
+        self._session_inflight: dict[str, asyncio.Task[ClientSession]] = {}
+
+        self._tools_cache: dict[str, tuple[MCPToolDefinition, ...]] = {}
+        self._tools_cache_epoch: dict[str, int] = {}
+        self._inflight_tools: dict[str, asyncio.Task[tuple[MCPToolDefinition, ...]]] = {}
+
+    def list_tools(self, provider: MCPProviderT, timeout_sec: float | None = None) -> tuple[MCPToolDefinition, ...]:
+        """List tools from an MCP provider (cached with request coalescing)."""
+        try:
+            return self._run_on_loop(self._list_tools_async(provider), timeout_sec)
+        except TimeoutError as exc:
+            timeout_label = f"{timeout_sec:.1f}" if timeout_sec is not None else "unknown"
+            raise MCPToolError(f"Timed out after {timeout_label}s while listing tools on {provider.name!r}.") from exc
+
+    def call_tools(
+        self,
+        calls: list[tuple[MCPProviderT, str, dict[str, Any]]],
+        *,
+        timeout_sec: float | None = None,
+    ) -> list[MCPToolResult]:
+        """Call multiple tools in parallel."""
+        if not calls:
+            return []
+        try:
+            return self._run_on_loop(self._call_tools_async(calls), timeout_sec)
+        except TimeoutError as exc:
+            timeout_label = f"{timeout_sec:.1f}" if timeout_sec is not None else "unknown"
+            raise MCPToolError(f"Timed out after {timeout_label}s while calling tools in parallel.") from exc
+
+    def clear_provider_caches(self, providers: list[MCPProviderT]) -> int:
+        """Clear caches and session pool entries for specific providers."""
+        if not providers:
+            return 0
+        if self._loop is not None and self._loop.is_running():
+            try:
+                return self._run_on_loop(self._clear_provider_caches_async(providers), timeout_sec=5)
+            except Exception:
+                logger.debug("Failed to clear provider caches on MCP IO service.", exc_info=True)
+                return 0
+        return self._clear_provider_caches_sync(providers)
+
+    def clear_tools_cache(self) -> None:
+        """Clear the list_tools cache (best effort)."""
+        if self._loop is not None and self._loop.is_running():
+            try:
+                self._run_on_loop(self._clear_tools_cache_async(), timeout_sec=5)
+                return
+            except Exception:
+                logger.debug("Failed to clear tools cache on MCP IO service.", exc_info=True)
+                return
+        self._clear_tools_cache_sync()
+
+    def get_cache_info(self) -> dict[str, Any]:
+        """Get cache statistics for list_tools."""
+        if self._loop is not None and self._loop.is_running():
+            try:
+                return self._run_on_loop(self._get_cache_info_async(), timeout_sec=5)
+            except Exception:
+                logger.debug("Failed to read tools cache info on MCP IO service.", exc_info=True)
+        return {"currsize": len(self._tools_cache), "providers": list(self._tools_cache.keys())}
+
+    def clear_session_pool(self) -> None:
+        """Clear all pooled MCP sessions (best effort)."""
+        if self._loop is not None and self._loop.is_running():
+            try:
+                self._run_on_loop(self._close_all_sessions_async(), timeout_sec=5)
+                return
+            except Exception:
+                logger.debug("Failed to clear session pool on MCP IO service.", exc_info=True)
+                # Fall through to sync cleanup
+        self._clear_session_pool_sync()
+
+    def get_session_pool_info(self) -> dict[str, Any]:
+        """Get information about the session pool."""
+        if self._loop is not None and self._loop.is_running():
+            try:
+                return self._run_on_loop(self._get_session_pool_info_async(), timeout_sec=5)
+            except Exception:
+                logger.debug("Failed to read session pool info on MCP IO service.", exc_info=True)
+        return {"active_sessions": len(self._sessions), "provider_keys": list(self._sessions.keys())}
+
+    def shutdown(self) -> None:
+        """Shutdown the MCP event loop and close all sessions."""
+        if self._loop is None:
+            self._reset_state()
+            return
+        try:
+            future = asyncio.run_coroutine_threadsafe(self._close_all_sessions_async(), self._loop)
+            try:
+                future.result(timeout=5)
+            except Exception:
+                pass
+            self._loop.call_soon_threadsafe(self._loop.stop)
+            if self._thread is not None:
+                self._thread.join(timeout=5)
+        finally:
+            self._loop = None
+            self._thread = None
+            self._reset_state()
+
+    def _ensure_loop(self) -> asyncio.AbstractEventLoop:
+        with self._loop_lock:
+            if self._loop is None or not self._loop.is_running():
+                loop = asyncio.new_event_loop()
+                self._loop = loop
+                self._thread = threading.Thread(
+                    target=self._run_loop,
+                    args=(loop,),
+                    daemon=True,
+                    name="MCP-EventLoop",
+                )
+                self._thread.start()
+                logger.debug("Started MCP background event loop")
+            # Capture local reference to avoid race with concurrent shutdown()
+            loop = self._loop
+        return loop
+
+    @staticmethod
+    def _run_loop(loop: asyncio.AbstractEventLoop) -> None:
+        asyncio.set_event_loop(loop)
+        loop.run_forever()
+
+    def _run_on_loop(self, coro: Coroutine[Any, Any, Any], timeout_sec: float | None) -> Any:
+        loop = self._ensure_loop()
+        future = asyncio.run_coroutine_threadsafe(coro, loop)
+        return future.result(timeout=timeout_sec)
+
+    async def _get_or_create_session(self, provider: MCPProviderT) -> ClientSession:
+        key = _provider_cache_key(provider)
+        session = self._sessions.get(key)
+        if session is not None:
+            return session
+
+        inflight = self._session_inflight.get(key)
+        if inflight is not None:
+            return await inflight
+
+        async def create_session() -> ClientSession:
+            ctx: Any | None = None
+            new_session: ClientSession | None = None
+            try:
+                if isinstance(provider, LocalStdioMCPProvider):
+                    params = StdioServerParameters(
+                        command=provider.command,
+                        args=provider.args,
+                        env=provider.env,
+                    )
+                    ctx = stdio_client(params)
+                else:
+                    headers = _build_auth_headers(provider.api_key)
+                    ctx = sse_client(provider.endpoint, headers=headers)
+
+                read, write = await ctx.__aenter__()
+                new_session = ClientSession(read, write)
+                await new_session.__aenter__()
+                await new_session.initialize()
+
+                self._sessions[key] = new_session
+                self._session_contexts[key] = ctx
+                logger.debug("Created pooled MCP session for provider %r", provider.name)
+                return new_session
+            except Exception:
+                if new_session is not None:
+                    try:
+                        await new_session.__aexit__(None, None, None)
+                    except Exception:
+                        pass
+                if ctx is not None:
+                    try:
+                        await ctx.__aexit__(None, None, None)
+                    except Exception:
+                        pass
+                raise
+
+        task = asyncio.create_task(create_session())
+        self._session_inflight[key] = task
+        try:
+            return await task
+        finally:
+            self._session_inflight.pop(key, None)
+
+    async def _list_tools_async(self, provider: MCPProviderT) -> tuple[MCPToolDefinition, ...]:
+        key = _provider_cache_key(provider)
+        cached = self._tools_cache.get(key)
+        if cached is not None:
+            return cached
+
+        inflight = self._inflight_tools.get(key)
+        if inflight is not None:
+            return await inflight
+
+        epoch = self._tools_cache_epoch.get(key, 0)
+
+        async def fetch_tools() -> tuple[MCPToolDefinition, ...]:
+            session = await self._get_or_create_session(provider)
+            result = await session.list_tools()
+            raw_tools = getattr(result, "tools", result)
+            if not isinstance(raw_tools, list):
+                raise MCPToolError("Unexpected response from MCP provider when listing tools.")
+            tools = tuple(_coerce_tool_definition(tool, MCPToolDefinition) for tool in raw_tools)
+            if self._tools_cache_epoch.get(key, 0) == epoch:
+                self._tools_cache[key] = tools
+                logger.debug("Cached tools for provider %r (%d tools)", provider.name, len(tools))
+            return tools
+
+        task = asyncio.create_task(fetch_tools())
+        self._inflight_tools[key] = task
+        try:
+            return await task
+        finally:
+            self._inflight_tools.pop(key, None)
+
+    async def _call_tool_async(
+        self,
+        provider: MCPProviderT,
+        tool_name: str,
+        arguments: dict[str, Any],
+    ) -> MCPToolResult:
+        session = await self._get_or_create_session(provider)
+        result = await session.call_tool(tool_name, arguments)
+
+        content = _serialize_tool_result_content(result)
+        is_error = getattr(result, "isError", None)
+        if is_error is None:
+            is_error = getattr(result, "is_error", False)
+
+        return MCPToolResult(content=content, is_error=bool(is_error))
+
+    async def _call_tools_async(
+        self,
+        calls: list[tuple[MCPProviderT, str, dict[str, Any]]],
+    ) -> list[MCPToolResult]:
+        return await asyncio.gather(*[self._call_tool_async(p, n, a) for p, n, a in calls])
+
+    async def _clear_provider_caches_async(self, providers: list[MCPProviderT]) -> int:
+        keys = [_provider_cache_key(provider) for provider in providers]
+        self._invalidate_tools_cache(keys)
+
+        cleared_count = 0
+        for key in keys:
+            session = self._sessions.pop(key, None)
+            ctx = self._session_contexts.pop(key, None)
+            if session is not None:
+                cleared_count += 1
+                try:
+                    await session.__aexit__(None, None, None)
+                except Exception:
+                    pass
+            if ctx is not None:
+                try:
+                    await ctx.__aexit__(None, None, None)
+                except Exception:
+                    pass
+
+        if cleared_count > 0:
+            logger.debug("Cleared %d provider cache entries", cleared_count)
+        return cleared_count
+
+    def _clear_provider_caches_sync(self, providers: list[MCPProviderT]) -> int:
+        keys = [_provider_cache_key(provider) for provider in providers]
+        self._invalidate_tools_cache(keys)
+
+        cleared_count = 0
+        for key in keys:
+            if key in self._sessions:
+                del self._sessions[key]
+                cleared_count += 1
+            if key in self._session_contexts:
+                del self._session_contexts[key]
+
+        if cleared_count > 0:
+            logger.debug("Cleared %d provider cache entries", cleared_count)
+        return cleared_count
+
+    async def _clear_tools_cache_async(self) -> None:
+        self._invalidate_tools_cache(self._all_tools_keys())
+
+    def _clear_tools_cache_sync(self) -> None:
+        self._invalidate_tools_cache(self._all_tools_keys())
+
+    async def _get_cache_info_async(self) -> dict[str, Any]:
+        return {"currsize": len(self._tools_cache), "providers": list(self._tools_cache.keys())}
+
+    async def _close_all_sessions_async(self) -> None:
+        for key in list(self._sessions.keys()):
+            session = self._sessions.pop(key, None)
+            ctx = self._session_contexts.pop(key, None)
+            if session is not None:
+                try:
+                    await session.__aexit__(None, None, None)
+                except Exception:
+                    pass
+            if ctx is not None:
+                try:
+                    await ctx.__aexit__(None, None, None)
+                except Exception:
+                    pass
+
+        for task in self._session_inflight.values():
+            task.cancel()
+        self._session_inflight.clear()
+
+    def _clear_session_pool_sync(self) -> None:
+        self._sessions.clear()
+        self._session_contexts.clear()
+        self._session_inflight.clear()
+
+    async def _get_session_pool_info_async(self) -> dict[str, Any]:
+        return {"active_sessions": len(self._sessions), "provider_keys": list(self._sessions.keys())}
+
+    def _invalidate_tools_cache(self, keys: Iterable[str]) -> None:
+        for key in keys:
+            self._tools_cache.pop(key, None)
+            self._tools_cache_epoch[key] = self._tools_cache_epoch.get(key, 0) + 1
+
+    def _all_tools_keys(self) -> set[str]:
+        return set(self._tools_cache) | set(self._inflight_tools) | set(self._tools_cache_epoch)
+
+    def _reset_state(self) -> None:
+        self._sessions.clear()
+        self._session_contexts.clear()
+        self._session_inflight.clear()
+        self._tools_cache.clear()
+        self._tools_cache_epoch.clear()
+        self._inflight_tools.clear()
+
+
+_MCP_IO_SERVICE = MCPIOService()
+atexit.register(_MCP_IO_SERVICE.shutdown)
+
+
+def list_tools(provider: MCPProviderT, timeout_sec: float | None = None) -> tuple[MCPToolDefinition, ...]:
+    """List tools from an MCP provider (cached with request coalescing)."""
+    return _MCP_IO_SERVICE.list_tools(provider, timeout_sec=timeout_sec)
+
+
+def call_tools(
+    calls: list[tuple[MCPProviderT, str, dict[str, Any]]],
+    *,
+    timeout_sec: float | None = None,
+) -> list[MCPToolResult]:
+    """Call multiple tools in parallel."""
+    return _MCP_IO_SERVICE.call_tools(calls, timeout_sec=timeout_sec)
+
+
+def clear_provider_caches(providers: list[MCPProviderT]) -> int:
+    """Clear all caches for specific MCP providers."""
+    return _MCP_IO_SERVICE.clear_provider_caches(providers)
+
+
+def clear_tools_cache() -> None:
+    """Clear the list_tools cache."""
+    _MCP_IO_SERVICE.clear_tools_cache()
+
+
+def get_cache_info() -> dict[str, Any]:
+    """Get cache statistics for list_tools."""
+    return _MCP_IO_SERVICE.get_cache_info()
+
+
+def clear_session_pool() -> None:
+    """Clear all pooled MCP sessions."""
+    _MCP_IO_SERVICE.clear_session_pool()
+
+
+def get_session_pool_info() -> dict[str, Any]:
+    """Get information about the session pool."""
+    return _MCP_IO_SERVICE.get_session_pool_info()
+
+
+def _build_auth_headers(api_key: str | None) -> dict[str, Any] | None:
+    """Build authentication headers for SSE client."""
+    if not api_key:
+        return None
+    return {"Authorization": f"Bearer {api_key}"}
+
+
+def _coerce_tool_definition(tool: Any, tool_definition_cls: type[MCPToolDefinition]) -> MCPToolDefinition:
+    """Coerce a tool from various formats into MCPToolDefinition."""
+    if isinstance(tool, dict):
+        name = tool.get("name")
+        description = tool.get("description")
+        input_schema = tool.get("inputSchema") or tool.get("input_schema")
+    else:
+        name = getattr(tool, "name", None)
+        description = getattr(tool, "description", None)
+        input_schema = getattr(tool, "inputSchema", None) or getattr(tool, "input_schema", None)
+
+    if not name:
+        raise MCPToolError("Encountered MCP tool without a name.")
+
+    return tool_definition_cls(name=name, description=description, input_schema=input_schema)
+
+
+def _serialize_tool_result_content(result: Any) -> str:
+    """Serialize tool result content to a string."""
+    content = getattr(result, "content", result)
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, dict):
+        return json.dumps(content)
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, str):
+                parts.append(item)
+                continue
+            if isinstance(item, dict):
+                if item.get("type") == "text":
+                    parts.append(str(item.get("text", "")))
+                else:
+                    parts.append(json.dumps(item))
+                continue
+            text_value = getattr(item, "text", None)
+            if text_value is not None:
+                parts.append(str(text_value))
+            else:
+                parts.append(str(item))
+        return "\n".join(parts)
+    return str(content)

data_designer/engine/mcp/registry.py

@@ -0,0 +1,203 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from data_designer.config.mcp import ToolConfig
+from data_designer.engine.model_provider import MCPProviderRegistry
+from data_designer.engine.secret_resolver import SecretResolver
+
+if TYPE_CHECKING:
+    from data_designer.engine.mcp.facade import MCPFacade
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class MCPToolDefinition:
+    """Definition of an MCP tool with its schema."""
+
+    name: str
+    description: str | None
+    input_schema: dict[str, Any] | None
+
+    def to_openai_tool_schema(self) -> dict[str, Any]:
+        """Convert this tool definition to OpenAI function calling format.
+
+        Returns:
+            A dictionary in OpenAI's tool schema format with 'type' set to
+            'function' and nested 'function' containing name, description,
+            and parameters.
+        """
+        schema = self.input_schema or {"type": "object", "properties": {}}
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description or "",
+                "parameters": schema,
+            },
+        }
+
+
+@dataclass(frozen=True)
+class MCPToolResult:
+    """Result from executing an MCP tool call."""
+
+    content: str
+    is_error: bool = False
+
+
+class MCPRegistry:
+    """Registry for MCP tool configurations and facades.
+
+    MCPRegistry manages ToolConfig instances by tool_alias and lazily creates
+    MCPFacade instances when requested. This is a config-only registry - all
+    actual MCP operations are delegated to the MCPFacade and io module.
+
+    This mirrors the ModelRegistry pattern for consistency across the codebase.
+    """
+
+    def __init__(
+        self,
+        *,
+        secret_resolver: SecretResolver,
+        mcp_provider_registry: MCPProviderRegistry,
+        mcp_facade_factory: Callable[[ToolConfig, SecretResolver, MCPProviderRegistry], MCPFacade],
+        tool_configs: list[ToolConfig] | None = None,
+    ) -> None:
+        """Initialize the MCPRegistry.
+
+        Args:
+            secret_resolver: Resolver for secrets referenced in provider configs.
+            mcp_provider_registry: Registry of MCP provider configurations.
+            mcp_facade_factory: Factory for creating MCPFacade instances.
+            tool_configs: Optional list of tool configurations to register.
+        """
+        self._secret_resolver = secret_resolver
+        self._mcp_provider_registry = mcp_provider_registry
+        self._mcp_facade_factory = mcp_facade_factory
+        self._tool_configs: dict[str, ToolConfig] = {}
+        self._facades: dict[str, MCPFacade] = {}
+        self._validated_tool_aliases: set[str] = set()
+
+        self._set_tool_configs(tool_configs)
+
+    @property
+    def tool_configs(self) -> dict[str, ToolConfig]:
+        """Get all registered tool configurations."""
+        return self._tool_configs
+
+    @property
+    def facades(self) -> dict[str, MCPFacade]:
+        """Get all instantiated facades."""
+        return self._facades
+
+    @property
+    def mcp_provider_registry(self) -> MCPProviderRegistry:
+        """Get the MCP provider registry."""
+        return self._mcp_provider_registry
+
+    def register_tool_configs(self, tool_configs: list[ToolConfig]) -> None:
+        """Register tool configurations at runtime.
+
+        Args:
+            tool_configs: List of tool configurations to register. If a configuration
+                with the same alias already exists, it will be overwritten.
+        """
+        self._set_tool_configs(list(self._tool_configs.values()) + tool_configs)
+
+    def get_mcp(self, *, tool_alias: str) -> MCPFacade:
+        """Get or lazily create an MCPFacade for the given tool alias.
+
+        Args:
+            tool_alias: The alias of the tool configuration.
+
+        Returns:
+            An MCPFacade configured for the specified tool alias.
+
+        Raises:
+            ValueError: If no tool config with the given alias is found.
+        """
+        if tool_alias not in self._tool_configs:
+            raise ValueError(f"No tool config with alias {tool_alias!r} found!")
+
+        if tool_alias not in self._facades:
+            self._facades[tool_alias] = self._create_facade(self._tool_configs[tool_alias])
+
+        return self._facades[tool_alias]
+
+    def get_tool_config(self, *, tool_alias: str) -> ToolConfig:
+        """Get a tool configuration by alias.
+
+        Args:
+            tool_alias: The alias of the tool configuration.
+
+        Returns:
+            The tool configuration.
+
+        Raises:
+            ValueError: If no tool config with the given alias is found.
+        """
+        if tool_alias not in self._tool_configs:
+            raise ValueError(f"No tool config with alias {tool_alias!r} found!")
+        return self._tool_configs[tool_alias]
+
+    def _set_tool_configs(self, tool_configs: list[ToolConfig] | None) -> None:
+        """Set tool configurations from a list."""
+        tool_configs = tool_configs or []
+        self._tool_configs = {tc.tool_alias: tc for tc in tool_configs}
+
+    def _create_facade(self, tool_config: ToolConfig) -> MCPFacade:
+        """Create an MCPFacade for a tool configuration."""
+        return self._mcp_facade_factory(tool_config, self._secret_resolver, self._mcp_provider_registry)
+
+    def _validate_tool_config_providers(self, tool_config: ToolConfig) -> None:
+        available_providers = {provider.name for provider in self._mcp_provider_registry.providers}
+        missing_providers = [provider for provider in tool_config.providers if provider not in available_providers]
+        if missing_providers:
+            available_list = sorted(available_providers) if available_providers else ["(none configured)"]
+            raise ValueError(
+                f"ToolConfig '{tool_config.tool_alias}' references provider(s) {missing_providers!r} "
+                f"which are not registered. Available providers: {available_list}"
+            )
+
+    def _validate_tool_alias(self, tool_alias: str) -> None:
+        if tool_alias not in self._tool_configs:
+            raise ValueError(f"No tool config with alias {tool_alias!r} found!")
+        tool_config = self._tool_configs[tool_alias]
+        self._validate_tool_config_providers(tool_config)
+        facade = self.get_mcp(tool_alias=tool_alias)
+        facade.get_tool_schemas()
+        self._validated_tool_aliases.add(tool_alias)
+
+    def run_health_check(self, tool_aliases: list[str]) -> None:
+        if not tool_aliases:
+            return
+        logger.info("🧰 Running health checks for MCP tools...")
+        for tool_alias in tool_aliases:
+            logger.info(f"  |-- 👀 Checking tools for tool alias {tool_alias!r}...")
+            try:
+                self._validate_tool_alias(tool_alias)
+                logger.info("  |-- ✅ Passed!")
+            except Exception:
+                logger.error("  |-- ❌ Failed!")
+                raise
+
+    def validate_no_duplicate_tool_names(self) -> None:
+        """Validate that no ToolConfig has duplicate tool names across its providers.
+
+        This method eagerly fetches tool schemas for all registered ToolConfigs,
+        which triggers duplicate tool name detection. This catches cases where
+        multiple providers in the same ToolConfig expose a tool with the same name.
+
+        Raises:
+            DuplicateToolNameError: If any ToolConfig has duplicate tool names across providers.
+        """
+        for tool_alias in self._tool_configs:
+            self._validate_tool_alias(tool_alias)