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

hud/environment/tests/test_tools.py

@@ -0,0 +1,208 @@
+"""Tests for @env.tool() decorator and tool operations."""
+
+from __future__ import annotations
+
+import pytest
+
+from hud.environment import Environment
+
+
+class TestToolDecorator:
+    """Tests for @env.tool() decorator."""
+
+    def test_tool_registers_function(self) -> None:
+        """@env.tool registers the function in tool manager."""
+        env = Environment("test-env")
+
+        @env.tool()
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        # Check tool was registered
+        tool_names = list(env._tool_manager._tools.keys())
+        assert "add" in tool_names
+
+    def test_tool_with_custom_name(self) -> None:
+        """@env.tool(name=...) uses custom name."""
+        env = Environment("test-env")
+
+        @env.tool(name="custom_add")
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        tool_names = list(env._tool_manager._tools.keys())
+        assert "custom_add" in tool_names
+        assert "add" not in tool_names
+
+    def test_tool_preserves_docstring(self) -> None:
+        """@env.tool preserves function docstring as description."""
+        env = Environment("test-env")
+
+        @env.tool()
+        def greet(name: str) -> str:
+            """Greet someone by name."""
+            return f"Hello, {name}!"
+
+        tool = env._tool_manager._tools.get("greet")
+        assert tool is not None
+        assert "Greet someone by name" in (tool.description or "")
+
+    def test_tool_async_function(self) -> None:
+        """@env.tool works with async functions."""
+        env = Environment("test-env")
+
+        @env.tool()
+        async def fetch_data(url: str) -> str:
+            """Fetch data from URL."""
+            return f"Data from {url}"
+
+        tool_names = list(env._tool_manager._tools.keys())
+        assert "fetch_data" in tool_names
+
+    def test_tool_returns_function(self) -> None:
+        """@env.tool returns the original function."""
+        env = Environment("test-env")
+
+        @env.tool()
+        def add(a: int, b: int) -> int:
+            return a + b
+
+        # Should be able to call it directly
+        assert add(2, 3) == 5
+
+
+class TestListTools:
+    """Tests for list_tools and as_tools."""
+
+    @pytest.mark.asyncio
+    async def test_as_tools_returns_registered_tools(self) -> None:
+        """as_tools returns list of registered MCP tools."""
+        env = Environment("test-env")
+
+        @env.tool()
+        def tool1() -> str:
+            return "1"
+
+        @env.tool()
+        def tool2() -> str:
+            return "2"
+
+        async with env:
+            tools = env.as_tools()
+            tool_names = [t.name for t in tools]
+            assert "tool1" in tool_names
+            assert "tool2" in tool_names
+
+    @pytest.mark.asyncio
+    async def test_as_tools_empty_when_no_tools(self) -> None:
+        """as_tools returns empty list when no tools registered."""
+        env = Environment("test-env")
+        async with env:
+            tools = env.as_tools()
+            # May have built-in _hud_submit tool
+            user_tools = [t for t in tools if not t.name.startswith("_")]
+            assert len(user_tools) == 0
+
+
+class TestCallTool:
+    """Tests for call_tool method."""
+
+    @pytest.mark.asyncio
+    async def test_call_tool_executes_function(self) -> None:
+        """call_tool executes registered tool function."""
+        env = Environment("test-env")
+        executed = []
+
+        @env.tool()
+        def greet(name: str) -> str:
+            executed.append(name)
+            return f"Hello, {name}!"
+
+        async with env:
+            result = await env.call_tool("greet", name="Alice")
+
+        assert executed == ["Alice"]
+        assert result is not None
+
+    @pytest.mark.asyncio
+    async def test_call_tool_async_function(self) -> None:
+        """call_tool works with async tool functions."""
+        env = Environment("test-env")
+
+        @env.tool()
+        async def async_greet(name: str) -> str:
+            return f"Hello, {name}!"
+
+        async with env:
+            result = await env.call_tool("async_greet", name="Bob")
+
+        assert result is not None
+
+    @pytest.mark.asyncio
+    async def test_call_tool_not_found(self) -> None:
+        """call_tool raises for unknown tool."""
+        env = Environment("test-env")
+
+        async with env:
+            with pytest.raises(ValueError, match="Tool not found"):
+                await env.call_tool("nonexistent")
+
+
+class TestMockMode:
+    """Tests for mock mode."""
+
+    def test_mock_mode_default_false(self) -> None:
+        """Mock mode is False by default."""
+        env = Environment("test-env")
+        assert env._mock_mode is False
+        assert env.is_mock is False
+
+    def test_mock_enables_mock_mode(self) -> None:
+        """mock() enables mock mode."""
+        env = Environment("test-env")
+        env.mock()
+        assert env._mock_mode is True
+        assert env.is_mock is True
+
+    def test_unmock_disables_mock_mode(self) -> None:
+        """unmock() disables mock mode."""
+        env = Environment("test-env")
+        env.mock()
+        env.unmock()
+        assert env._mock_mode is False
+
+    def test_mock_returns_self_for_chaining(self) -> None:
+        """mock() returns self for chaining."""
+        env = Environment("test-env")
+        result = env.mock()
+        assert result is env
+
+    def test_mock_tool_sets_custom_output(self) -> None:
+        """mock_tool() sets custom output for a tool."""
+        env = Environment("test-env")
+        env.mock_tool("navigate", "Custom result")
+        assert env._mock_outputs["navigate"] == "Custom result"
+
+    @pytest.mark.asyncio
+    async def test_mock_mode_returns_mock_response(self) -> None:
+        """Mock mode returns mock response instead of executing tool."""
+        env = Environment("test-env")
+        call_count = 0
+
+        @env.tool()
+        def real_tool() -> str:
+            nonlocal call_count
+            call_count += 1
+            return "real result"
+
+        env.mock()
+        env.mock_tool("real_tool", "mocked result")
+
+        async with env:
+            result = await env.call_tool("real_tool")
+
+        # Tool should not be called in mock mode
+        assert call_count == 0
+        # Should get the mock result
+        assert result is not None

hud/environment/types.py

@@ -0,0 +1,23 @@
+"""Environment types for configuration and tracing."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+__all__ = ["EnvConfig"]
+
+
+class EnvConfig(BaseModel):
+    """Environment configuration for Tasks.
+
+    Specifies which hub to connect to and optional tool filtering.
+
+    Attributes:
+        name: Hub name to connect via connect_hub() (e.g., "browser", "sheets")
+        include: Optional whitelist of tool names to include
+        exclude: Optional blacklist of tool names to exclude
+    """
+
+    name: str = Field(description="Hub name to connect to")
+    include: list[str] | None = Field(default=None, description="Whitelist of tool names")
+    exclude: list[str] | None = Field(default=None, description="Blacklist of tool names")

hud/environment/utils/__init__.py

@@ -0,0 +1,35 @@
+"""Environment utilities."""
+
+from hud.environment.utils.formats import (
+    ToolFormat,
+    format_result,
+    parse_tool_call,
+    parse_tool_calls,
+    result_to_string,
+)
+from hud.environment.utils.schema import (
+    ensure_strict_schema,
+    json_type_to_python,
+    schema_to_pydantic,
+)
+from hud.environment.utils.tool_wrappers import (
+    create_async_tool_fn,
+    create_sync_tool_fn,
+    create_tool_fns,
+    stringify_result,
+)
+
+__all__ = [
+    "ToolFormat",
+    "create_async_tool_fn",
+    "create_sync_tool_fn",
+    "create_tool_fns",
+    "ensure_strict_schema",
+    "format_result",
+    "json_type_to_python",
+    "parse_tool_call",
+    "parse_tool_calls",
+    "result_to_string",
+    "schema_to_pydantic",
+    "stringify_result",
+]

hud/environment/utils/formats.py

@@ -0,0 +1,215 @@
+"""Tool format parsing and conversion for OpenAI, Claude, Gemini, and MCP."""
+
+from __future__ import annotations
+
+import json
+from enum import Enum, auto
+from typing import Any
+
+from hud.types import MCPToolCall, MCPToolResult
+
+__all__ = [
+    "ToolFormat",
+    "format_result",
+    "parse_tool_call",
+    "parse_tool_calls",
+    "result_to_string",
+]
+
+
+class ToolFormat(Enum):
+    """Detected tool call format."""
+
+    OPENAI = auto()  # function.arguments as JSON string
+    CLAUDE = auto()  # type="tool_use", input as dict
+    GEMINI = auto()  # functionCall with args
+    MCP = auto()  # name + arguments
+
+
+# -----------------------------------------------------------------------------
+# Parsing
+# -----------------------------------------------------------------------------
+
+
+def _to_dict(obj: Any) -> dict[str, Any]:
+    """Convert object to dict for uniform processing."""
+    if isinstance(obj, dict):
+        return obj
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump()
+    if hasattr(obj, "__dict__"):
+        return vars(obj)
+    raise ValueError(f"Cannot convert {type(obj).__name__} to dict")
+
+
+def _parse_json_args(args: Any) -> dict[str, Any]:
+    """Parse arguments, handling JSON strings."""
+    if not args:
+        return {}
+    if isinstance(args, str):
+        try:
+            return json.loads(args)
+        except json.JSONDecodeError:
+            return {}
+    return args
+
+
+def parse_tool_call(call: Any, **kwargs: Any) -> tuple[MCPToolCall, ToolFormat]:
+    """Parse any tool call format into (MCPToolCall, ToolFormat).
+
+    Supports:
+        - String (tool name only, or with kwargs)
+        - Tuple: (name,), (name, args), (name, args, id)
+        - MCPToolCall
+        - OpenAI: {function: {name, arguments}, id}
+        - Claude: {type: "tool_use", name, input, id}
+        - Gemini: {functionCall: {name, args}} or {name, args}
+        - Generic: {name, arguments}
+
+    Args:
+        call: Tool call in any supported format.
+        **kwargs: Additional arguments (merged when call is a string).
+
+    Returns:
+        Tuple of (MCPToolCall, ToolFormat) for the parsed call.
+
+    Raises:
+        ValueError: If format is unrecognized.
+    """
+    # Primitives
+    if isinstance(call, str):
+        return MCPToolCall(name=call, arguments=kwargs or {}), ToolFormat.MCP
+
+    if isinstance(call, tuple):
+        tc = MCPToolCall(name=call[0], arguments=call[1] if len(call) > 1 else {})
+        if len(call) > 2:
+            tc.id = call[2]
+        return tc, ToolFormat.MCP
+
+    if isinstance(call, MCPToolCall):
+        return call, ToolFormat.MCP
+
+    # Convert to dict
+    d = _to_dict(call)
+
+    # OpenAI: {function: {name, arguments}, id}
+    if "function" in d:
+        f = _to_dict(d["function"]) if not isinstance(d["function"], dict) else d["function"]
+        tc = MCPToolCall(name=f["name"], arguments=_parse_json_args(f.get("arguments")))
+        if d.get("id"):
+            tc.id = d["id"]
+        return tc, ToolFormat.OPENAI
+
+    # Claude: {type: "tool_use", name, input, id}
+    if d.get("type") == "tool_use":
+        tc = MCPToolCall(name=d["name"], arguments=d.get("input") or {})
+        if d.get("id"):
+            tc.id = d["id"]
+        return tc, ToolFormat.CLAUDE
+
+    # Gemini: {functionCall: {name, args}} or {name, args}
+    if "functionCall" in d:
+        fc = d["functionCall"]
+        return MCPToolCall(name=fc["name"], arguments=fc.get("args") or {}), ToolFormat.GEMINI
+
+    if "args" in d and "name" in d and "arguments" not in d:
+        return MCPToolCall(name=d["name"], arguments=d.get("args") or {}), ToolFormat.GEMINI
+
+    # Generic: {name, arguments/input}
+    if "name" in d:
+        tc = MCPToolCall(name=d["name"], arguments=d.get("arguments") or d.get("input") or {})
+        if d.get("id"):
+            tc.id = d["id"]
+        return tc, ToolFormat.MCP
+
+    raise ValueError(f"Unrecognized tool call format: {list(d.keys())}")
+
+
+def _is_tool_block(item: Any) -> bool:
+    """Check if item is a tool call (not text/other content)."""
+    t = item.get("type") if isinstance(item, dict) else getattr(item, "type", None)
+    return t is None or t in ("tool_use", "function")
+
+
+def parse_tool_calls(calls: Any) -> list[tuple[MCPToolCall, ToolFormat]]:
+    """Parse multiple tool calls, filtering non-tool content (e.g. Claude TextBlock).
+
+    Args:
+        calls: Single call or list of calls in any format.
+
+    Returns:
+        List of (MCPToolCall, ToolFormat) tuples.
+    """
+    if calls is None:
+        return []
+    if not isinstance(calls, list):
+        try:
+            return [parse_tool_call(calls)]
+        except ValueError:
+            return []
+
+    results = []
+    for item in calls:
+        if not _is_tool_block(item):
+            continue
+        try:
+            results.append(parse_tool_call(item))
+        except ValueError:
+            continue
+    return results
+
+
+# -----------------------------------------------------------------------------
+# Result Formatting
+# -----------------------------------------------------------------------------
+
+
+def result_to_string(result: MCPToolResult) -> str:
+    """Convert MCPToolResult content to string.
+
+    Args:
+        result: MCP tool result with content blocks.
+
+    Returns:
+        String representation of the result content.
+    """
+    if not result.content:
+        return ""
+    parts = []
+    for block in result.content:
+        if (text := getattr(block, "text", None)) is not None:
+            parts.append(str(text))
+        elif (data := getattr(block, "data", None)) is not None:
+            parts.append(f"[binary: {len(data)} bytes]")
+    return "\n".join(parts)
+
+
+def format_result(result: MCPToolResult, tc: MCPToolCall, fmt: ToolFormat) -> Any:
+    """Format MCPToolResult based on the input format.
+
+    Args:
+        result: MCP tool result.
+        tc: Original tool call (for id/name).
+        fmt: Target format.
+
+    Returns:
+        OpenAI: {"role": "tool", "tool_call_id": ..., "content": ...}
+        Claude: {"type": "tool_result", "tool_use_id": ..., "content": ..., "is_error"?: bool}
+        Gemini: {"functionResponse": {"name": ..., "response": {"result": ...}}}
+        MCP: MCPToolResult unchanged
+    """
+    content = result_to_string(result)
+
+    if fmt == ToolFormat.OPENAI:
+        return {"role": "tool", "tool_call_id": tc.id, "content": content}
+
+    if fmt == ToolFormat.CLAUDE:
+        r: dict[str, Any] = {"type": "tool_result", "tool_use_id": tc.id, "content": content}
+        if result.isError:
+            r["is_error"] = True
+        return r
+
+    if fmt == ToolFormat.GEMINI:
+        return {"functionResponse": {"name": tc.name, "response": {"result": content}}}
+
+    return result  # MCP format - return as-is

hud/environment/utils/schema.py

@@ -0,0 +1,171 @@
+"""Schema utilities for tool definitions."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+__all__ = [
+    "ensure_strict_schema",
+    "json_type_to_python",
+    "schema_to_pydantic",
+    "validate_openai_schema",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_strict_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Ensure a JSON schema is compatible with OpenAI's strict mode.
+
+    OpenAI strict mode requires:
+    - additionalProperties: false on all objects
+    - All properties must be in required
+
+    Args:
+        schema: Original JSON schema.
+
+    Returns:
+        Modified schema for strict mode.
+    """
+    schema = dict(schema)
+
+    if schema.get("type") == "object":
+        schema["additionalProperties"] = False
+
+        if "properties" in schema:
+            # All properties must be required
+            schema["required"] = list(schema["properties"].keys())
+
+            # Recursively process nested objects
+            for prop_schema in schema["properties"].values():
+                if isinstance(prop_schema, dict):
+                    _ensure_strict_recursive(prop_schema)
+
+    return schema
+
+
+def _ensure_strict_recursive(schema: dict[str, Any]) -> None:
+    """Recursively apply strict mode to nested schemas."""
+    if schema.get("type") == "object":
+        schema["additionalProperties"] = False
+        if "properties" in schema:
+            schema["required"] = list(schema["properties"].keys())
+            for prop_schema in schema["properties"].values():
+                if isinstance(prop_schema, dict):
+                    _ensure_strict_recursive(prop_schema)
+
+    elif schema.get("type") == "array" and "items" in schema:
+        if isinstance(schema["items"], dict):
+            _ensure_strict_recursive(schema["items"])
+
+
+def schema_to_pydantic(name: str, schema: dict[str, Any]) -> type:
+    """Convert JSON schema to a Pydantic model.
+
+    Args:
+        name: Model name (used for class name).
+        schema: JSON schema with properties.
+
+    Returns:
+        Dynamically created Pydantic model class.
+    """
+    from pydantic import Field, create_model
+
+    properties = schema.get("properties", {})
+    required = set(schema.get("required", []))
+
+    fields = {}
+    for prop_name, prop_schema in properties.items():
+        prop_type = json_type_to_python(prop_schema.get("type", "string"))
+        default = ... if prop_name in required else None
+        description = prop_schema.get("description", "")
+        fields[prop_name] = (prop_type, Field(default=default, description=description))
+
+    return create_model(f"{name}Input", **fields)
+
+
+def json_type_to_python(json_type: str) -> type:
+    """Map JSON schema type to Python type.
+
+    Args:
+        json_type: JSON schema type string.
+
+    Returns:
+        Corresponding Python type.
+    """
+    mapping = {
+        "string": str,
+        "integer": int,
+        "number": float,
+        "boolean": bool,
+        "array": list,
+        "object": dict,
+    }
+    return mapping.get(json_type, str)
+
+
+def validate_openai_schema(
+    schema: dict[str, Any],
+    tool_name: str = "unknown",
+    path: str = "",
+) -> list[str]:
+    """Validate a JSON schema for OpenAI API compatibility.
+
+    OpenAI's API has specific requirements for tool schemas:
+    - Arrays must have 'items' (not 'prefixItems' which tuples generate)
+    - Certain schema features like 'prefixItems' are not supported
+
+    Args:
+        schema: JSON schema to validate.
+        tool_name: Name of the tool (for error messages).
+        path: Current path in schema (for error context).
+
+    Returns:
+        List of validation error messages. Empty if valid.
+    """
+    errors: list[str] = []
+
+    if not isinstance(schema, dict):
+        return errors
+
+    # Check for prefixItems (generated by tuple types)
+    if "prefixItems" in schema:
+        errors.append(
+            f"Tool '{tool_name}' has 'prefixItems' at {path or 'root'} "
+            "(likely from tuple type). Use list[Model] instead of tuple."
+        )
+
+    # Check arrays have 'items'
+    if schema.get("type") == "array" and "items" not in schema and "prefixItems" not in schema:
+        errors.append(
+            f"Tool '{tool_name}' has array at {path or 'root'} without 'items'. "
+            "OpenAI requires 'items' for array schemas."
+        )
+
+    # Recursively check nested schemas
+    # Check properties
+    if "properties" in schema:
+        for prop_name, prop_schema in schema["properties"].items():
+            prop_path = f"{path}.{prop_name}" if path else prop_name
+            errors.extend(validate_openai_schema(prop_schema, tool_name, prop_path))
+
+    # Check items
+    if "items" in schema and isinstance(schema["items"], dict):
+        items_path = f"{path}[items]" if path else "[items]"
+        errors.extend(validate_openai_schema(schema["items"], tool_name, items_path))
+
+    # Check anyOf/oneOf/allOf
+    for key in ("anyOf", "oneOf", "allOf"):
+        if key in schema:
+            for i, sub_schema in enumerate(schema[key]):
+                sub_path = f"{path}.{key}[{i}]" if path else f"{key}[{i}]"
+                errors.extend(validate_openai_schema(sub_schema, tool_name, sub_path))
+
+    # Check $defs (definitions)
+    if "$defs" in schema:
+        for def_name, def_schema in schema["$defs"].items():
+            def_path = f"$defs.{def_name}"
+            errors.extend(validate_openai_schema(def_schema, tool_name, def_path))
+
+    return errors