hud-python 0.4.45__py3-none-any.whl → 0.5.1__py3-none-any.whl

hud/environment/connectors/base.py

@@ -0,0 +1,68 @@
+"""Base connector mixin with shared helper."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from fastmcp.tools.tool import Tool
+
+    from hud.environment.connection import ConnectionType, Connector
+
+__all__ = ["BaseConnectorMixin"]
+
+
+class BaseConnectorMixin:
+    """Base mixin providing connection helper.
+
+    Requires:
+        _connections: dict[str, Connector]
+    """
+
+    _connections: dict[str, Connector]
+
+    def _add_connection(
+        self,
+        name: str,
+        transport: Any,
+        *,
+        connection_type: ConnectionType,
+        auth: str | None = None,
+        prefix: str | None = None,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+        transform: Callable[[Tool], Tool | None] | None = None,
+    ) -> Any:
+        """Add a connection to the environment.
+
+        Args:
+            name: Connection name/alias.
+            transport: FastMCP transport (URL, config dict, etc.).
+            connection_type: LOCAL or REMOTE - determines parallelization.
+            auth: Authorization header value.
+            prefix: Prefix for tool names.
+            include: Only include these tools.
+            exclude: Exclude these tools.
+            transform: Transform function for tools.
+
+        Returns:
+            self for chaining.
+        """
+        from hud.environment.connection import ConnectionConfig, Connector
+
+        config = ConnectionConfig(
+            prefix=prefix,
+            include=include,
+            exclude=exclude,
+            transform=transform,
+        )
+        self._connections[name] = Connector(
+            transport,
+            config,
+            name,
+            connection_type=connection_type,
+            auth=auth,
+        )
+        return self

hud/environment/connectors/local.py

@@ -0,0 +1,177 @@
+"""Local connection connectors - Docker image, FastAPI, MCPServer."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hud.environment.connectors.mcp_config import MCPConfigConnectorMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from fastmcp.tools.tool import Tool
+
+__all__ = ["LocalConnectorMixin"]
+
+
+class LocalConnectorMixin(MCPConfigConnectorMixin):
+    """Mixin providing local connection methods.
+
+    Methods:
+        connect_image(image) - Run Docker image via stdio
+        connect_fastapi(app) - Mount FastAPI app as MCP server
+        connect_server(server) - Mount any MCPServer/FastMCP directly
+
+    Inherits connect_mcp() from MCPConfigConnectorMixin.
+
+    Note: include_router() is inherited from MCPServer (via FastMCP).
+    """
+
+    def connect_image(
+        self,
+        image: str,
+        *,
+        alias: str | None = None,
+        docker_args: list[str] | None = None,
+        env_vars: dict[str, str] | None = None,
+        prefix: str | None = None,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+        transform: Callable[[Tool], Tool | None] | None = None,
+    ) -> Any:
+        """Connect to a Docker image via stdio.
+
+        Creates an MCP config that runs: docker run -i --rm {image}
+        Environment variables from `.env` files are auto-injected.
+
+        Example:
+            ```python
+            env = Environment("my-env")
+            env.connect_image("mcp/fetch")
+
+            async with env:
+                result = await env.call_tool("fetch", url="https://example.com")
+            ```
+        """
+        from hud.cli.utils.docker import create_docker_run_command
+
+        cmd = create_docker_run_command(
+            image=image,
+            docker_args=docker_args,
+            extra_env=env_vars,
+            interactive=True,
+            remove=True,
+        )
+
+        name = alias or image
+        mcp_config = {
+            name: {
+                "command": cmd[0],
+                "args": cmd[1:],
+            }
+        }
+        return self.connect_mcp(
+            mcp_config,
+            alias=name,
+            prefix=prefix,
+            include=include,
+            exclude=exclude,
+            transform=transform,
+        )
+
+    def connect_fastapi(
+        self,
+        app: Any,
+        *,
+        name: str | None = None,
+        prefix: str | None = None,
+        include_hidden: bool = True,
+    ) -> Any:
+        """Import a FastAPI application's routes as MCP tools.
+
+        Uses FastMCP's from_fastapi() to convert FastAPI endpoints to MCP tools,
+        then imports them synchronously so they're available immediately.
+
+        Args:
+            app: FastAPI application instance
+            name: Custom name for the server (defaults to app.title)
+            prefix: Optional prefix for tool names
+            include_hidden: If True (default), includes routes with include_in_schema=False
+
+        Example:
+            ```python
+            from fastapi import FastAPI
+
+            api = FastAPI()
+
+
+            @api.get("/users/{user_id}", operation_id="get_user")
+            def get_user(user_id: int):
+                return {"id": user_id, "name": "Alice"}
+
+
+            env = Environment("my-env")
+            env.connect_fastapi(api)
+
+            async with env:
+                result = await env.call_tool("get_user", user_id=1)
+            ```
+
+        Tip: Use operation_id in FastAPI decorators for cleaner tool names.
+        """
+        from fastmcp import FastMCP
+
+        # Temporarily enable hidden routes for OpenAPI generation
+        hidden_routes: list[Any] = []
+        if include_hidden:
+            for route in getattr(app, "routes", []):
+                if hasattr(route, "include_in_schema") and not route.include_in_schema:
+                    hidden_routes.append(route)
+                    route.include_in_schema = True
+            # Clear cached openapi schema so it regenerates
+            if hasattr(app, "openapi_schema"):
+                app.openapi_schema = None
+
+        try:
+            server_name = name or getattr(app, "title", None) or "fastapi"
+            mcp_server = FastMCP.from_fastapi(app=app, name=server_name)
+            # Use include_router for synchronous import (tools available immediately)
+            self.include_router(mcp_server, prefix=prefix)  # type: ignore
+        finally:
+            # Restore original states
+            for route in hidden_routes:
+                route.include_in_schema = False
+            if hidden_routes and hasattr(app, "openapi_schema"):
+                app.openapi_schema = None  # Clear cache again
+
+        return self
+
+    def connect_server(
+        self,
+        server: Any,
+        *,
+        prefix: str | None = None,
+    ) -> Any:
+        """Import an MCPServer or FastMCP instance's tools directly.
+
+        Example:
+            ```python
+            from fastmcp import FastMCP
+
+            tools = FastMCP("tools")
+
+
+            @tools.tool
+            def greet(name: str) -> str:
+                return f"Hello, {name}!"
+
+
+            env = Environment("my-env")
+            env.connect_server(tools)
+
+            async with env:
+                result = await env.call_tool("greet", name="World")
+            ```
+        """
+        self.include_router(server, prefix=prefix)  # type: ignore
+        return self

hud/environment/connectors/mcp_config.py

@@ -0,0 +1,109 @@
+"""MCP config connection connectors."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hud.environment.connectors.base import BaseConnectorMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from fastmcp.tools.tool import Tool
+
+__all__ = ["MCPConfigConnectorMixin"]
+
+
+class MCPConfigConnectorMixin(BaseConnectorMixin):
+    """Mixin providing mcp_config connection methods."""
+
+    def connect_mcp(
+        self,
+        config: dict[str, dict[str, Any]],
+        *,
+        alias: str | None = None,
+        prefix: str | None = None,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+        transform: Callable[[Tool], Tool | None] | None = None,
+    ) -> Any:
+        """Connect using an mcp_config dictionary (single server).
+
+        Auto-detects LOCAL (stdio) vs REMOTE (URL) based on config.
+
+        Example:
+            ```python
+            env = Environment("my-env")
+
+            # Stdio server
+            env.connect_mcp(
+                {
+                    "filesystem": {
+                        "command": "npx",
+                        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+                    }
+                }
+            )
+
+            async with env:
+                await env.call_tool("read_file", path="/tmp/test.txt")
+            ```
+        """
+        from hud.environment.connection import ConnectionType
+
+        name = alias or next(iter(config.keys()), "mcp")
+        server_config = next(iter(config.values()), {})
+
+        is_local = "command" in server_config or "args" in server_config
+        conn_type = ConnectionType.LOCAL if is_local else ConnectionType.REMOTE
+
+        return self._add_connection(
+            name,
+            config,
+            connection_type=conn_type,
+            prefix=prefix,
+            include=include,
+            exclude=exclude,
+            transform=transform,
+        )
+
+    def connect_mcp_config(
+        self,
+        mcp_config: dict[str, dict[str, Any]],
+        **kwargs: Any,
+    ) -> Any:
+        """Connect multiple servers from an mcp_config dictionary.
+
+        Example:
+            ```python
+            env = Environment("my-env")
+
+            # Claude Desktop style config
+            env.connect_mcp_config(
+                {
+                    "filesystem": {
+                        "command": "npx",
+                        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+                    },
+                    "github": {
+                        "command": "npx",
+                        "args": ["-y", "@modelcontextprotocol/server-github"],
+                        "env": {"GITHUB_TOKEN": "..."},
+                    },
+                }
+            )
+
+            async with env:
+                await env.call_tool("read_file", path="/tmp/test.txt")
+                await env.call_tool("search_repositories", query="mcp")
+            ```
+        """
+        # Store mcp_config for serialization (v4 format)
+        # Merge with existing if called multiple times
+        if not hasattr(self, "_mcp_config") or self._mcp_config is None:
+            self._mcp_config = {}
+        self._mcp_config.update(mcp_config)
+
+        for server_name, server_config in mcp_config.items():
+            self.connect_mcp({server_name: server_config}, alias=server_name, **kwargs)
+        return self

hud/environment/connectors/openai.py

@@ -0,0 +1,101 @@
+"""OpenAI Agents SDK connectors - import tools from OpenAI agents."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+__all__ = ["OpenAIConnectorMixin"]
+
+
+class OpenAIConnectorMixin:
+    """Mixin providing OpenAI Agents SDK connector methods."""
+
+    # These are defined on Environment/MCPServer
+    _tool_manager: Any
+
+    def connect_function_tools(
+        self,
+        tools: list[Any],
+        *,
+        prefix: str | None = None,
+    ) -> Any:
+        """Import FunctionTools from the OpenAI Agents SDK.
+
+        Wraps each tool so calls go through HUD with telemetry.
+
+        Example:
+            ```python
+            from agents import function_tool
+
+
+            @function_tool
+            def search(query: str) -> str:
+                '''Search for information.'''
+                return f"Results for {query}"
+
+
+            @function_tool
+            def calculate(expression: str) -> float:
+                '''Evaluate a math expression.'''
+                return eval(expression)
+
+
+            env = Environment("my-env")
+            env.connect_function_tools([search, calculate])
+
+            async with env:
+                result = await env.call_tool("search", query="MCP protocol")
+            ```
+
+        Note:
+            Requires `openai-agents`: pip install openai-agents
+        """
+        try:
+            from agents import FunctionTool
+        except ImportError as e:
+            raise ImportError(
+                "openai-agents is required for connect_function_tools. "
+                "Install with: pip install openai-agents"
+            ) from e
+
+        for tool in tools:
+            if isinstance(tool, FunctionTool):
+                self._add_openai_function_tool(tool, prefix)
+
+        return self
+
+    def _add_openai_function_tool(self, tool: Any, prefix: str | None) -> None:
+        """Convert OpenAI FunctionTool to local MCP tool."""
+        name = f"{prefix}_{tool.name}" if prefix else tool.name
+
+        # Get the original invoke function
+        original_invoke = tool.on_invoke_tool
+
+        # Create wrapper that calls the original
+        async def invoke(**arguments: Any) -> Any:
+            # OpenAI's on_invoke_tool expects (ToolContext, str_json_args)
+            # We need to create a minimal context
+            from agents.tool_context import ToolContext
+
+            ctx = ToolContext(context=None)
+            result = await original_invoke(ctx, json.dumps(arguments))
+            return result
+
+        # Set function metadata for FastMCP
+        invoke.__name__ = name
+        invoke.__doc__ = tool.description
+
+        # Register using FastMCP's tool decorator mechanism
+        # We access the internal _tool_manager from MCPServer
+        from fastmcp.tools import Tool as FastMCPTool
+
+        fastmcp_tool = FastMCPTool.from_function(
+            fn=invoke,
+            name=name,
+            description=tool.description,
+        )
+        # Override the schema with OpenAI's (more accurate)
+        fastmcp_tool.parameters = tool.params_json_schema
+
+        self._tool_manager.add_tool(fastmcp_tool)

hud/environment/connectors/remote.py

@@ -0,0 +1,172 @@
+"""Remote connection connectors - HUD Hub, URL, OpenAPI."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, cast
+
+from hud.environment.connectors.mcp_config import MCPConfigConnectorMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from fastmcp.tools.tool import Tool
+
+__all__ = ["RemoteConnectorMixin"]
+
+logger = logging.getLogger(__name__)
+
+
+class RemoteConnectorMixin(MCPConfigConnectorMixin):
+    """Mixin providing remote connection methods.
+
+    Note: include_router() is inherited from MCPServer (via FastMCP).
+    """
+
+    def connect_hub(
+        self,
+        slug: str,
+        *,
+        alias: str | None = None,
+        prefix: str | None = None,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+        transform: Callable[[Tool], Tool | None] | None = None,
+    ) -> Any:
+        """Connect to a HUD Hub environment.
+
+        Creates an MCP connection to the HUD API with the hub slug in headers.
+
+        Example:
+            ```python
+            env = Environment("my-env")
+            env.connect_hub("browser")
+
+            async with env:
+                await env.call_tool("navigate", url="https://google.com")
+            ```
+        """
+        from hud.settings import settings
+
+        logger.info("Connecting to hub environment: %s", slug)
+
+        # Store hub config for serialization (v5 format)
+        # Note: Only first hub is stored for serialization (task configs use single hub)
+        if not hasattr(self, "_hub_config") or self._hub_config is None:
+            hub_config: dict[str, Any] = {"name": slug}
+            if include:
+                hub_config["include"] = include
+            if exclude:
+                hub_config["exclude"] = exclude
+            self._hub_config = hub_config
+
+        # Create mcp_config with standard MCP URL and hub slug in headers
+        # Note: Authorization is injected at request time by httpx/aiohttp hooks
+        # in hud.eval.instrument (uses contextvar for api_key).
+        mcp_config = {
+            "hud": {
+                "url": settings.hud_mcp_url,
+                "headers": {"Environment-Name": slug},
+            }
+        }
+
+        self.connect_mcp_config(
+            mcp_config, prefix=prefix, include=include, exclude=exclude, transform=transform
+        )
+        logger.info("Hub connected: %s", slug)
+        return self
+
+    def connect_url(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        alias: str | None = None,
+        prefix: str | None = None,
+        include: list[str] | None = None,
+        exclude: list[str] | None = None,
+        transform: Callable[[Tool], Tool | None] | None = None,
+    ) -> Any:
+        """Connect to an MCP server via URL.
+
+        Example:
+            ```python
+            env = Environment("my-env")
+            env.connect_url(
+                "https://mcp.example.com",
+                headers={"Authorization": "Bearer token"},
+            )
+
+            async with env:
+                await env.call_tool("search", query="hello")
+            ```
+        """
+        from hud.environment.connection import ConnectionType
+
+        auth = headers.get("Authorization") if headers else None
+        return self._add_connection(
+            alias or url,
+            url,
+            connection_type=ConnectionType.REMOTE,
+            auth=auth,
+            prefix=prefix,
+            include=include,
+            exclude=exclude,
+            transform=transform,
+        )
+
+    def connect_openapi(
+        self,
+        openapi_spec: dict[str, Any] | str,
+        *,
+        base_url: str | None = None,
+        headers: dict[str, str] | None = None,
+        name: str | None = None,
+        prefix: str | None = None,
+        timeout: float = 30.0,
+    ) -> Any:
+        """Mount an OpenAPI specification as an MCP server.
+
+        Converts REST API endpoints to MCP tools. Base URL is auto-inferred
+        from the spec URL when possible.
+
+        Example:
+            ```python
+            env = Environment("my-env")
+            env.connect_openapi("https://petstore.swagger.io/v2/swagger.json")
+
+            async with env:
+                result = await env.call_tool("getPetById", petId=1)
+            ```
+        """
+        from urllib.parse import urlparse
+
+        import httpx
+        from fastmcp import FastMCP
+
+        if isinstance(openapi_spec, str):
+            if openapi_spec.startswith(("http://", "https://")):
+                if base_url is None:
+                    parsed = urlparse(openapi_spec)
+                    base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+                resp = httpx.get(openapi_spec, headers=headers)
+                resp.raise_for_status()
+                openapi_spec = resp.json()
+            else:
+                import json
+
+                with open(openapi_spec) as f:
+                    openapi_spec = json.load(f)
+
+        if base_url is None:
+            raise ValueError("base_url is required when openapi_spec is a dict or file")
+
+        client = httpx.AsyncClient(base_url=base_url, headers=headers or {}, timeout=timeout)
+        mcp_server = FastMCP.from_openapi(
+            openapi_spec=cast("dict[str, Any]", openapi_spec),
+            client=client,
+            name=name or "openapi",
+        )
+        self.include_router(mcp_server, prefix=prefix)  # type: ignore
+        return self