hud-python 0.4.11__py3-none-any.whl → 0.4.12__py3-none-any.whl

hud/telemetry/tests/test_trace.py

@@ -0,0 +1,63 @@
+"""Tests for telemetry trace functionality."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from hud.telemetry.trace import trace
+
+
+class TestTraceAPI:
+    """Tests for trace API function."""
+
+    def test_trace_with_disabled_telemetry_and_no_api_key(self):
+        """Test trace behavior when telemetry is disabled and no API key."""
+        # Mock settings to disable telemetry and remove API key
+        mock_settings = type("Settings", (), {"telemetry_enabled": False, "api_key": None})()
+
+        with (
+            patch("hud.settings.get_settings", return_value=mock_settings),
+            patch("hud.telemetry.trace.OtelTrace") as mock_otel_trace,
+        ):
+            mock_otel_trace.return_value.__enter__.return_value = "custom-otlp-trace"
+
+            with trace("test-trace") as task_run_id:
+                # Should use placeholder ID for custom backends
+                assert task_run_id == "custom-otlp-trace"
+
+    def test_trace_with_enabled_telemetry_and_api_key(self):
+        """Test trace behavior when telemetry is enabled with API key."""
+        mock_settings = type("Settings", (), {"telemetry_enabled": True, "api_key": "test-key"})()
+
+        with (
+            patch("hud.settings.get_settings", return_value=mock_settings),
+            patch("hud.telemetry.trace.OtelTrace") as mock_otel_trace,
+            patch("hud.telemetry.trace.uuid.uuid4") as mock_uuid,
+        ):
+            mock_uuid.return_value = "mock-uuid-123"
+            mock_otel_trace.return_value.__enter__.return_value = "mock-uuid-123"
+
+            with trace("test-trace") as task_run_id:
+                # Should use generated UUID
+                assert task_run_id == "mock-uuid-123"
+
+    def test_trace_with_no_api_key(self):
+        """Test trace behavior with no API key (custom backend scenario)."""
+        mock_settings = type(
+            "Settings",
+            (),
+            {
+                "telemetry_enabled": True,  # Enabled but no API key
+                "api_key": None,
+            },
+        )()
+
+        with (
+            patch("hud.settings.get_settings", return_value=mock_settings),
+            patch("hud.telemetry.trace.OtelTrace") as mock_otel_trace,
+        ):
+            mock_otel_trace.return_value.__enter__.return_value = "custom-otlp-trace"
+
+            with trace("test-trace") as task_run_id:
+                # Should use custom backend placeholder
+                assert task_run_id == "custom-otlp-trace"

hud/tools/base.py

@@ -38,6 +38,7 @@ class BaseTool(ABC):
         name: str | None = None,
         title: str | None = None,
         description: str | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> None:
         """Initialize the tool.
 
@@ -50,11 +51,13 @@ class BaseTool(ABC):
             name: Tool name for MCP registration (auto-generated from class name if not provided)
             title: Human-readable display name for the tool (auto-generated from class name)
             description: Tool description (auto-generated from docstring if not provided)
+            meta: Metadata to include in MCP tool listing (e.g., resolution info)
         """
         self.env = env
         self.name = name or self.__class__.__name__.lower().replace("tool", "")
         self.title = title or self.__class__.__name__.replace("Tool", "").replace("_", " ").title()
         self.description = description or (self.__doc__.strip() if self.__doc__ else None)
+        self.meta = meta
 
         # Expose attributes FastMCP expects when registering an instance directly
         self.__name__ = self.name  # FastMCP uses fn.__name__ if name param omitted
@@ -93,6 +96,7 @@ class BaseTool(ABC):
                 name=self.name,
                 title=self.title,
                 description=self.description,
+                meta=self.meta,
             )
         return self._mcp_tool
 
@@ -113,6 +117,7 @@ class BaseHub(FastMCP):
         env: Any | None = None,
         title: str | None = None,
         description: str | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> None:
         """Create a new BaseHub.
 
@@ -124,6 +129,8 @@ class BaseHub(FastMCP):
             Optional long-lived environment object. Stored on the server
             instance (``layer.env``) and therefore available to every request
             via ``ctx.fastmcp.env``.
+        meta:
+            Metadata to include in MCP tool listing.
         """
 
         # Naming scheme for hidden objects
@@ -141,7 +148,7 @@ class BaseHub(FastMCP):
         async def _dispatch(  # noqa: ANN202
             name: str,
             arguments: dict | str | None = None,
-            ctx=None,  # noqa: ANN001
+            ctx: Any | None = None,
         ):
             """Gateway to hidden tools.
 
@@ -176,6 +183,7 @@ class BaseHub(FastMCP):
             title=dispatcher_title,
             description=dispatcher_desc,
             tags=set(),
+            meta=meta,
         )
         self._tool_manager.add_tool(dispatcher_tool)
 
@@ -344,8 +352,17 @@ class BaseHub(FastMCP):
                             "enum": [t[0] for t in sorted(internal_tools)],
                         },
                         "arguments": {
-                            "type": "object",
-                            "description": "Arguments to pass to the internal tool. See description for details on each tool's parameters.",  # noqa: E501
+                            "anyOf": [
+                                {
+                                    "type": "object",
+                                    "description": "Arguments object to pass to the internal tool",
+                                },
+                                {
+                                    "type": "string",
+                                    "description": "JSON string of arguments to pass to the internal tool",  # noqa: E501
+                                },
+                            ],
+                            "description": "Arguments to pass to the internal tool. Can be an object or JSON string. See description for details on each tool's parameters.",  # noqa: E501
                         },
                     },
                     "required": ["name", "arguments"],

hud/tools/computer/hud.py

@@ -58,20 +58,29 @@ class HudComputerTool(BaseTool):
             title: Human-readable display name for the tool (auto-generated from class name)
             description: Tool description (auto-generated from docstring if not provided)
         """
+        # This is the width and height the agent thinks it operates in
+        # By default, use subclass's width and height
+        # If specifically set to None, use environment width and height
+        self.width = width or computer_settings.DISPLAY_WIDTH
+        self.height = height or computer_settings.DISPLAY_HEIGHT
+
+        # Build metadata with resolution info
+        meta = {
+            "resolution": {
+                "width": self.width,
+                "height": self.height,
+            }
+        }
+
         # Initialize base tool with executor as env
         super().__init__(
             env=executor,
             name=name or "computer",
             title=title or "Computer Control",
             description=description or "Control computer with mouse, keyboard, and screenshots",
+            meta=meta,
         )
 
-        # This is the width and height the agent thinks it operates in
-        # By default, use subclass's width and height
-        # If specifically set to None, use environment width and height
-        self.width = width or computer_settings.DISPLAY_WIDTH
-        self.height = height or computer_settings.DISPLAY_HEIGHT
-
         # This is the static width and height of the environment screen
         # And the width and height of the screenshots taken by the tool
         self.environment_width = computer_settings.DISPLAY_WIDTH

hud/tools/executors/tests/test_base_executor.py

@@ -336,3 +336,30 @@ class TestBaseExecutor:
 
         assert result1.base64_image == screenshot1
         assert result2.base64_image == screenshot1
+
+
+class TestLazyImports:
+    """Tests for lazy import functionality in executors module."""
+
+    def test_lazy_import_pyautogui_executor(self):
+        """Test lazy import of PyAutoGUIExecutor."""
+        # This should trigger the __getattr__ function and import PyAutoGUIExecutor
+        from hud.tools.executors import PyAutoGUIExecutor
+
+        # Verify it's imported correctly
+        assert PyAutoGUIExecutor.__name__ == "PyAutoGUIExecutor"
+
+    def test_lazy_import_xdo_executor(self):
+        """Test lazy import of XDOExecutor."""
+        # This should trigger the __getattr__ function and import XDOExecutor
+        from hud.tools.executors import XDOExecutor
+
+        # Verify it's imported correctly
+        assert XDOExecutor.__name__ == "XDOExecutor"
+
+    def test_lazy_import_invalid_attribute(self):
+        """Test lazy import with invalid attribute name."""
+        import hud.tools.executors as executors_module
+
+        with pytest.raises(AttributeError, match="module '.*' has no attribute 'InvalidExecutor'"):
+            _ = executors_module.InvalidExecutor

hud/tools/response.py

@@ -12,7 +12,7 @@ if TYPE_CHECKING:
 class ResponseTool(BaseTool):
     """
     Protocol for handling responses within environments.
-    
+
     This abstract tool defines the interface for response handling in environments.
     Subclasses should implement the __call__ method to handle responses according
     to their specific needs.
@@ -36,18 +36,22 @@ class ResponseTool(BaseTool):
                 return blocks
     """
 
-    def __init__(self, name: str, title: str, description: str):
+    name: str = "response"
+    title: str = "Response Tool"
+    description: str = "Send a text response or list of messages to the environment"
+
+    def __init__(
+        self, name: str | None = None, title: str | None = None, description: str | None = None
+    ) -> None:
         super().__init__(
-            name=name or "response",
-            title=title or "Response Tool",
-            description=description or "Send a text response or list of messages to the environment",
+            name=name or self.name,
+            title=title or self.title,
+            description=description or self.description,
         )
 
     @abstractmethod
     async def __call__(
-        self,
-        response: str | None = None,
-        messages: list[ContentBlock] | None = None
+        self, response: str | None = None, messages: list[ContentBlock] | None = None
     ) -> list[ContentBlock]:
         """Handle response or messages and return as ContentBlocks.
 

hud/tools/tests/test_response.py

@@ -0,0 +1,60 @@
+"""Tests for ResponseTool class."""
+
+from __future__ import annotations
+
+import pytest
+
+from hud.tools.response import ResponseTool
+
+
+class ConcreteResponseTool(ResponseTool):
+    """Concrete implementation for testing."""
+
+    async def __call__(self, response: str | None = None, messages=None):
+        """Concrete implementation."""
+        from mcp.types import TextContent
+
+        return [TextContent(text=response or "test", type="text")]
+
+
+class TestResponseTool:
+    """Tests for ResponseTool abstract class."""
+
+    def test_init_with_defaults(self):
+        """Test initialization with default values."""
+        tool = ConcreteResponseTool()
+        assert tool.name == "response"
+        assert tool.title == "Response Tool"
+        assert tool.description == "Send a text response or list of messages to the environment"
+
+    def test_init_with_custom_values(self):
+        """Test initialization with custom values."""
+        tool = ConcreteResponseTool(
+            name="custom_response", title="Custom Response Tool", description="Custom description"
+        )
+        assert tool.name == "custom_response"
+        assert tool.title == "Custom Response Tool"
+        assert tool.description == "Custom description"
+
+    def test_abstract_method_not_implemented(self):
+        """Test that abstract method raises NotImplementedError when not implemented."""
+
+        # Create a concrete tool to test the abstract method's NotImplementedError
+        tool = ConcreteResponseTool()
+
+        # This should trigger the NotImplementedError in the abstract method
+        with pytest.raises(NotImplementedError, match="Subclasses must implement __call__"):
+            # Call the parent abstract method directly to hit the raise line
+            import asyncio
+
+            asyncio.run(ResponseTool.__call__(tool, "test"))  # type: ignore[attr-defined]
+
+    @pytest.mark.asyncio
+    async def test_concrete_implementation(self):
+        """Test that concrete implementation works correctly."""
+        tool = ConcreteResponseTool()
+        result = await tool("Hello, World!")
+
+        assert len(result) == 1
+        assert result[0].text == "Hello, World!"
+        assert result[0].type == "text"

hud/tools/tests/test_tools_init.py

@@ -0,0 +1,49 @@
+"""Tests for hud.tools.__init__ module."""
+
+from __future__ import annotations
+
+import pytest
+
+
+class TestToolsInit:
+    """Tests for the tools package initialization."""
+
+    def test_lazy_import_anthropic_computer_tool(self):
+        """Test lazy import of AnthropicComputerTool."""
+        from hud.tools import AnthropicComputerTool
+
+        # Verify it's imported correctly
+        assert AnthropicComputerTool.__name__ == "AnthropicComputerTool"
+
+    def test_lazy_import_hud_computer_tool(self):
+        """Test lazy import of HudComputerTool."""
+        from hud.tools import HudComputerTool
+
+        # Verify it's imported correctly
+        assert HudComputerTool.__name__ == "HudComputerTool"
+
+    def test_lazy_import_openai_computer_tool(self):
+        """Test lazy import of OpenAIComputerTool."""
+        from hud.tools import OpenAIComputerTool
+
+        # Verify it's imported correctly
+        assert OpenAIComputerTool.__name__ == "OpenAIComputerTool"
+
+    def test_lazy_import_invalid_attribute(self):
+        """Test lazy import with invalid attribute name."""
+        import hud.tools as tools_module
+
+        with pytest.raises(AttributeError, match="module '.*' has no attribute 'InvalidTool'"):
+            _ = tools_module.InvalidTool
+
+    def test_direct_imports_available(self):
+        """Test that directly imported tools are available."""
+        from hud.tools import BaseHub, BaseTool, BashTool, EditTool, PlaywrightTool, ResponseTool
+
+        # All should be available
+        assert BaseHub is not None
+        assert BaseTool is not None
+        assert BashTool is not None
+        assert EditTool is not None
+        assert PlaywrightTool is not None
+        assert ResponseTool is not None

hud/utils/design.py

@@ -93,10 +93,10 @@ class HUDDesign:
         """
         console = self._stderr_console if stderr else self._stdout_console
         console.print(f"[default not bold]{message}[/default not bold]")
-    
+
     def print(self, message: str, stderr: bool = True) -> None:
         """Print a message.
-        
+
         Args:
             message: The message to print
             stderr: If True, output to stderr (default), otherwise stdout
@@ -136,7 +136,9 @@ class HUDDesign:
         console = self._stderr_console if stderr else self._stdout_console
         console.print(f"[default not bold]{json_str}[/default not bold]")
 
-    def key_value_table(self, data: dict[str, str], show_header: bool = False, stderr: bool = True) -> None:
+    def key_value_table(
+        self, data: dict[str, str], show_header: bool = False, stderr: bool = True
+    ) -> None:
         """Print a key-value table.
 
         Args:
@@ -197,7 +199,14 @@ class HUDDesign:
         console = self._stderr_console if stderr else self._stdout_console
         console.print(f"\n[yellow]💡 Hint: {hint}[/yellow]")
 
-    def status_item(self, label: str, value: str, status: str = "success", primary: bool = False, stderr: bool = True) -> None:
+    def status_item(
+        self,
+        label: str,
+        value: str,
+        status: str = "success",
+        primary: bool = False,
+        stderr: bool = True,
+    ) -> None:
         """Print a status item with indicator.
 
         Args:
@@ -211,18 +220,20 @@ class HUDDesign:
             "success": f"[{GREEN} not bold]✓[/{GREEN} not bold]",
             "error": f"[{RED} not bold]✗[/{RED} not bold]",
             "warning": "[yellow]⚠[/yellow]",
-            "info": f"[{DIM}]•[/{DIM}]"
+            "info": f"[{DIM}]•[/{DIM}]",
         }
-        
+
         indicator = indicators.get(status, indicators["info"])
         console = self._stderr_console if stderr else self._stdout_console
-        
+
         if primary:
             console.print(f"{indicator} {label}: [bold cyan]{value}[/bold cyan]")
         else:
             console.print(f"{indicator} {label}: {value}")
 
-    def command_example(self, command: str, description: str | None = None, stderr: bool = True) -> None:
+    def command_example(
+        self, command: str, description: str | None = None, stderr: bool = True
+    ) -> None:
         """Print a command example with cyan highlighting.
 
         Args:

hud/utils/mcp.py

@@ -23,7 +23,7 @@ def patch_mcp_config(mcp_config: dict[str, dict[str, Any]], patch: MCPConfigPatc
 
     for server_cfg in mcp_config.values():
         url = server_cfg.get("url", "")
-        
+
         # 1) HTTP header lane (only for hud MCP servers)
         if hud_mcp_url in url and patch.headers:
             for key, value in patch.headers.items():
@@ -37,9 +37,11 @@ def patch_mcp_config(mcp_config: dict[str, dict[str, Any]], patch: MCPConfigPatc
                 meta.setdefault(key, value)
 
 
-def setup_hud_telemetry(mcp_config: dict[str, dict[str, Any]], auto_trace: bool = True) -> Any | None:
+def setup_hud_telemetry(
+    mcp_config: dict[str, dict[str, Any]], auto_trace: bool = True
+) -> Any | None:
     """Setup telemetry for hud servers.
-    
+
     Returns:
         The auto-created trace context manager if one was created, None otherwise.
         Caller is responsible for exiting the context manager.
@@ -47,12 +49,22 @@ def setup_hud_telemetry(mcp_config: dict[str, dict[str, Any]], auto_trace: bool
     if not mcp_config:
         raise ValueError("Please run initialize() before setting up client-side telemetry")
 
+    # Check if there are any HUD servers to setup telemetry for
+    hud_mcp_url = settings.hud_mcp_url
+    has_hud_servers = any(
+        hud_mcp_url in server_cfg.get("url", "") for server_cfg in mcp_config.values()
+    )
+
+    # If no HUD servers, no need for telemetry setup
+    if not has_hud_servers:
+        return None
+
     from hud.otel import get_current_task_run_id
     from hud.telemetry import trace
 
     run_id = get_current_task_run_id()
     auto_trace_cm = None
-    
+
     if not run_id and auto_trace:
         auto_trace_cm = trace("My Trace")
         run_id = auto_trace_cm.__enter__()
@@ -63,5 +75,5 @@ def setup_hud_telemetry(mcp_config: dict[str, dict[str, Any]], auto_trace: bool
             mcp_config,
             MCPConfigPatch(headers={"Run-Id": run_id}, meta={"run_id": run_id}),
         )
-    
+
     return auto_trace_cm

hud/utils/tests/test_mcp.py

@@ -0,0 +1,112 @@
+"""Tests for MCP utility functions."""
+
+from __future__ import annotations
+
+import pytest
+
+from hud.utils.mcp import MCPConfigPatch, patch_mcp_config, setup_hud_telemetry
+
+
+class TestPatchMCPConfig:
+    """Tests for patch_mcp_config function."""
+
+    def test_patch_headers_for_hud_servers(self):
+        """Test patching headers for HUD MCP servers."""
+        from hud.settings import get_settings
+
+        settings = get_settings()
+
+        # Create an MCP config with a HUD server URL
+        mcp_config = {"test_server": {"url": f"{settings.hud_mcp_url}/test"}}
+
+        # Create patch with headers
+        patch = MCPConfigPatch(headers={"X-Test-Header": "test-value"}, meta=None)
+
+        # Apply patch
+        patch_mcp_config(mcp_config, patch)
+
+        # Verify headers were added
+        assert "headers" in mcp_config["test_server"]
+        assert mcp_config["test_server"]["headers"]["X-Test-Header"] == "test-value"  # type: ignore[index]
+
+    def test_patch_headers_preserves_existing(self):
+        """Test that existing headers are preserved."""
+        from hud.settings import get_settings
+
+        settings = get_settings()
+
+        # Create config with existing headers
+        mcp_config = {
+            "test_server": {
+                "url": f"{settings.hud_mcp_url}/test",
+                "headers": {"Existing-Header": "existing-value"},
+            }
+        }
+
+        patch = MCPConfigPatch(
+            headers={"X-Test-Header": "test-value", "Existing-Header": "new-value"},
+            meta=None,
+        )
+
+        patch_mcp_config(mcp_config, patch)
+
+        # Existing header should be preserved, new one added
+        assert mcp_config["test_server"]["headers"]["Existing-Header"] == "existing-value"
+        assert mcp_config["test_server"]["headers"]["X-Test-Header"] == "test-value"
+
+    def test_patch_meta_for_all_servers(self):
+        """Test patching metadata for all servers."""
+        mcp_config = {
+            "server1": {"url": "http://example.com"},
+            "server2": {"url": "http://other.com"},
+        }
+
+        patch = MCPConfigPatch(headers=None, meta={"test_key": "test_value"})
+
+        patch_mcp_config(mcp_config, patch)
+
+        # Meta should be added to both servers
+        assert mcp_config["server1"]["meta"]["test_key"] == "test_value"  # type: ignore[index]
+        assert mcp_config["server2"]["meta"]["test_key"] == "test_value"  # type: ignore[index]
+
+    def test_patch_meta_preserves_existing(self):
+        """Test that existing meta is preserved."""
+        mcp_config = {
+            "test_server": {"url": "http://example.com", "meta": {"existing_key": "existing_value"}}
+        }
+
+        patch = MCPConfigPatch(
+            headers=None,
+            meta={"test_key": "test_value", "existing_key": "new_value"},
+        )
+
+        patch_mcp_config(mcp_config, patch)
+
+        # Existing meta should be preserved, new one added
+        assert mcp_config["test_server"]["meta"]["existing_key"] == "existing_value"
+        assert mcp_config["test_server"]["meta"]["test_key"] == "test_value"
+
+
+class TestSetupHUDTelemetry:
+    """Tests for setup_hud_telemetry function."""
+
+    def test_empty_config_raises_error(self):
+        """Test that empty config raises ValueError."""
+        with pytest.raises(
+            ValueError, match="Please run initialize\\(\\) before setting up client-side telemetry"
+        ):
+            setup_hud_telemetry({})
+
+    def test_none_config_raises_error(self):
+        """Test that None config raises ValueError."""
+        with pytest.raises(
+            ValueError, match="Please run initialize\\(\\) before setting up client-side telemetry"
+        ):
+            setup_hud_telemetry(None)  # type: ignore[arg-type]
+
+    def test_valid_config_returns_none_when_no_hud_servers(self):
+        """Test that valid config with no HUD servers returns None."""
+        mcp_config = {"test_server": {"url": "http://example.com"}}
+
+        result = setup_hud_telemetry(mcp_config)
+        assert result is None

hud/utils/tests/test_version.py

@@ -5,4 +5,4 @@ def test_import():
     """Test that the package can be imported."""
     import hud
 
-    assert hud.__version__ == "0.4.11"
+    assert hud.__version__ == "0.4.12"

hud/version.py

@@ -4,4 +4,4 @@ Version information for the HUD SDK.
 
 from __future__ import annotations
 
-__version__ = "0.4.11"
+__version__ = "0.4.12"