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

hud/tools/tests/test_types.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import pytest
+from mcp.types import ImageContent, TextContent
+
+from hud.tools.types import ContentResult, EvaluationResult, ToolError
+
+
+def test_evaluation_result_defaults():
+    """Test EvaluationResult with default values."""
+    result = EvaluationResult()
+
+    assert result.reward == 0.0
+    assert result.done is False
+    assert result.content is None
+    assert result.info == {}
+    assert result.isError is False
+
+
+def test_evaluation_result_with_values():
+    """Test EvaluationResult with custom values."""
+    result = EvaluationResult(
+        reward=0.95,
+        done=True,
+        content="Task completed successfully",
+        info={"steps": 5},
+        isError=False,
+    )
+
+    assert result.reward == 0.95
+    assert result.done is True
+    assert result.content == "Task completed successfully"
+    assert result.info == {"steps": 5}
+    assert result.isError is False
+
+
+def test_content_result_defaults():
+    """Test ContentResult with default values."""
+    result = ContentResult()
+
+    assert result.output is None
+    assert result.error is None
+    assert result.base64_image is None
+    assert result.system is None
+
+
+def test_content_result_with_values():
+    """Test ContentResult with custom values."""
+    result = ContentResult(
+        output="Command executed",
+        error="No errors",
+        base64_image="base64data",
+        system="System message",
+    )
+
+    assert result.output == "Command executed"
+    assert result.error == "No errors"
+    assert result.base64_image == "base64data"
+    assert result.system == "System message"
+
+
+def test_content_result_add_both_output():
+    """Test adding two ContentResults with output."""
+    result1 = ContentResult(output="Part 1")
+    result2 = ContentResult(output=" Part 2")
+
+    combined = result1 + result2
+
+    assert combined.output == "Part 1 Part 2"
+    assert combined.error is None
+    assert combined.base64_image is None
+
+
+def test_content_result_add_both_error():
+    """Test adding two ContentResults with errors."""
+    result1 = ContentResult(error="Error 1")
+    result2 = ContentResult(error=" Error 2")
+
+    combined = result1 + result2
+
+    assert combined.error == "Error 1 Error 2"
+    assert combined.output is None
+
+
+def test_content_result_add_both_system():
+    """Test adding two ContentResults with system messages."""
+    result1 = ContentResult(system="System 1")
+    result2 = ContentResult(system=" System 2")
+
+    combined = result1 + result2
+
+    assert combined.system == "System 1 System 2"
+
+
+def test_content_result_add_one_sided():
+    """Test adding ContentResults where only one has values."""
+    result1 = ContentResult(output="Output")
+    result2 = ContentResult(error="Error")
+
+    combined = result1 + result2
+
+    assert combined.output == "Output"
+    assert combined.error == "Error"
+
+
+def test_content_result_add_images_raises_error():
+    """Test that combining two results with images raises an error."""
+    result1 = ContentResult(base64_image="image1")
+    result2 = ContentResult(base64_image="image2")
+
+    with pytest.raises(ValueError, match="Cannot combine tool results"):
+        _ = result1 + result2
+
+
+def test_content_result_add_one_image():
+    """Test adding ContentResults where only one has an image."""
+    result1 = ContentResult(base64_image="image1")
+    result2 = ContentResult(output="Output")
+
+    combined = result1 + result2
+
+    assert combined.base64_image == "image1"
+    assert combined.output == "Output"
+
+
+def test_content_result_to_content_blocks_output():
+    """Test converting ContentResult with output to content blocks."""
+    result = ContentResult(output="Test output")
+
+    blocks = result.to_content_blocks()
+
+    assert len(blocks) == 1
+    assert isinstance(blocks[0], TextContent)
+    assert blocks[0].text == "Test output"
+
+
+def test_content_result_to_content_blocks_error():
+    """Test converting ContentResult with error to content blocks."""
+    result = ContentResult(error="Test error")
+
+    blocks = result.to_content_blocks()
+
+    assert len(blocks) == 1
+    assert isinstance(blocks[0], TextContent)
+    assert blocks[0].text == "Test error"
+
+
+def test_content_result_to_content_blocks_image():
+    """Test converting ContentResult with image to content blocks."""
+    result = ContentResult(base64_image="base64data")
+
+    blocks = result.to_content_blocks()
+
+    assert len(blocks) == 1
+    assert isinstance(blocks[0], ImageContent)
+    assert blocks[0].data == "base64data"
+    assert blocks[0].mimeType == "image/png"
+
+
+def test_content_result_to_content_blocks_all():
+    """Test converting ContentResult with all fields to content blocks."""
+    result = ContentResult(
+        output="Output",
+        error="Error",
+        base64_image="image",
+    )
+
+    blocks = result.to_content_blocks()
+
+    assert len(blocks) == 3
+    assert isinstance(blocks[0], TextContent)
+    assert blocks[0].text == "Output"
+    assert isinstance(blocks[1], TextContent)
+    assert blocks[1].text == "Error"
+    assert isinstance(blocks[2], ImageContent)
+    assert blocks[2].data == "image"
+
+
+def test_content_result_to_content_blocks_empty():
+    """Test converting empty ContentResult to content blocks."""
+    result = ContentResult()
+
+    blocks = result.to_content_blocks()
+
+    assert len(blocks) == 0
+
+
+def test_tool_error():
+    """Test ToolError exception."""
+    error = ToolError("Test error message")
+
+    assert isinstance(error, Exception)
+    assert str(error) == "Test error message"

hud/tools/types.py

@@ -6,6 +6,18 @@ from mcp.types import ContentBlock, ImageContent, TextContent
 from pydantic import BaseModel, ConfigDict, Field
 
 
+class Coordinate(BaseModel):
+    """A coordinate point with x and y values.
+
+    Used for path-based actions like drag operations.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    x: int = Field(..., description="X coordinate")
+    y: int = Field(..., description="Y coordinate")
+
+
 class EvaluationResult(BaseModel):
     """Standard evaluation result format."""
 
@@ -28,6 +40,7 @@ class ContentResult(BaseModel):
     error: str | None = Field(default=None, description="Error message")
     base64_image: str | None = Field(default=None, description="Base64-encoded image")
     system: str | None = Field(default=None, description="System message")
+    url: str | None = Field(default=None, description="Current page URL (for browser automation)")
 
     def __add__(self, other: ContentResult) -> ContentResult:
         def combine_fields(
@@ -44,6 +57,7 @@ class ContentResult(BaseModel):
             error=combine_fields(self.error, other.error),
             base64_image=combine_fields(self.base64_image, other.base64_image, False),
             system=combine_fields(self.system, other.system),
+            url=combine_fields(self.url, other.url, False),
         )
 
     def to_content_blocks(self) -> list[ContentBlock]:
@@ -55,7 +69,7 @@ class ContentResult(BaseModel):
             result: ContentResult to convert
 
         Returns:
-            List of ContentBlock
+            List of ContentBlock with URL embedded as metadata if available
         """
         blocks: list[ContentBlock] = []
 
@@ -65,6 +79,12 @@ class ContentResult(BaseModel):
             blocks.append(TextContent(text=self.error, type="text"))
         if self.base64_image:
             blocks.append(ImageContent(data=self.base64_image, mimeType="image/png", type="image"))
+
+        # Add URL as a special metadata text block (for Gemini Computer Use)
+        # Always include URL if set, even if it's a placeholder like "about:blank"
+        if self.url:
+            blocks.append(TextContent(text=f"__URL__:{self.url}", type="text"))
+
         return blocks
 
 

hud/types.py

@@ -1,34 +1,116 @@
 from __future__ import annotations
 
-import contextlib
 import json
 import logging
 import uuid
-from collections import defaultdict
-from string import Template
+from enum import Enum
 from typing import Any, Literal
 
 import mcp.types as types
 from mcp.types import CallToolRequestParams, CallToolResult
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator
 
 from hud.settings import settings
+from hud.utils.env import resolve_env_vars as _resolve_env_vars
 from hud.utils.tool_shorthand import normalize_to_tool_call_dict
 
 logger = logging.getLogger(__name__)
 
+# Guard to ensure we only log missing HUD_API_KEY once
+_missing_api_key_error_logged: bool = False
 
-class Task(BaseModel):
+
+class AgentType(str, Enum):
+    CLAUDE = "claude"
+    OPENAI = "openai"
+    OPERATOR = "operator"
+    GEMINI = "gemini"
+    GEMINI_CUA = "gemini_cua"
+    OPENAI_COMPATIBLE = "openai_compatible"
+    INTEGRATION_TEST = "integration_test"
+
+    @property
+    def cls(self) -> type:
+        from hud.agents import OpenAIAgent, OperatorAgent
+        from hud.agents.claude import ClaudeAgent
+        from hud.agents.gemini import GeminiAgent
+        from hud.agents.gemini_cua import GeminiCUAAgent
+        from hud.agents.openai_chat import OpenAIChatAgent
+
+        mapping: dict[AgentType, type] = {
+            AgentType.CLAUDE: ClaudeAgent,
+            AgentType.OPENAI: OpenAIAgent,
+            AgentType.OPERATOR: OperatorAgent,
+            AgentType.GEMINI: GeminiAgent,
+            AgentType.GEMINI_CUA: GeminiCUAAgent,
+            AgentType.OPENAI_COMPATIBLE: OpenAIChatAgent,
+        }
+        if self == AgentType.INTEGRATION_TEST:
+            from hud.agents.misc.integration_test_agent import IntegrationTestRunner
+
+            return IntegrationTestRunner
+        if self not in mapping:
+            raise ValueError(f"Unsupported agent type: {self}")
+        return mapping[self]
+
+
+class BaseAgentConfig(BaseModel):
+    """Agent configuration for LLM-specific settings.
+
+    Note: allowed_tools, disallowed_tools, append_setup_output, and initial_screenshot
+    are kept for backwards compatibility with v4 task configs but are no longer applied
+    at the agent level. These should be configured on the Environment/Task instead.
     """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid", populate_by_name=True)
+
+    # Model identifier - use 'model' (preferred) or 'checkpoint_name' (alias)
+    model: str | None = Field(
+        default=None, validation_alias=AliasChoices("model", "checkpoint_name")
+    )
+    model_name: str = "Agent"  # Human-readable display name
+
+    # LLM-specific setting
+    system_prompt: str | None = None
+
+    # Deprecated: kept for backwards compat with v4 task configs, not applied by agent
+    allowed_tools: list[str] | None = None
+    disallowed_tools: list[str] | None = None
+    append_setup_output: bool = True
+    append_setup_tool: bool = True  # Alias for append_setup_output (backwards compat)
+    initial_screenshot: bool = True
+
+    @property
+    def checkpoint_name(self) -> str | None:
+        """Alias for model (for backwards compatibility)."""
+        return self.model
+
+
+class LegacyTask(BaseModel):
+    """
+    DEPRECATED: Use Task from env() instead.
+
     A task configuration that can be used to create a task.
 
     The mcp_config field supports environment variable substitution using
     template placeholders in the format ${VAR_NAME} or ${VAR_NAME:default_value}.
 
-    Example:
+    .. deprecated:: 0.5.0
+        LegacyTask is deprecated in v0.5.0 and will be removed in v0.6.0
+        (no earlier than March 1st, 2026).
+
+        Use one of these migration paths:
+
+        1. Quick conversion: ``Task.from_v4(legacy_task)`` converts LegacyTask to Task
+        2. Full migration: Use ``@env.scenario()`` with setup code before first yield
+           and evaluate code after first yield
+
+        See https://docs.hud.ai/migration for the full migration guide.
+
+    Example (deprecated):
         mcp_config: {
             "hud": {
-                "url": "${HUD_MCP_URL:https://mcp.hud.so/v3/mcp}",
+                "url": "${HUD_MCP_URL:https://mcp.hud.ai/v3/mcp}",
                 "headers": {
                     "Authorization": "Bearer ${HUD_API_KEY}",
                     "Mcp-Image": "your-mcp-image"
@@ -43,10 +125,23 @@ class Task(BaseModel):
     setup_tool: MCPToolCall | list[MCPToolCall] | None = None
     evaluate_tool: MCPToolCall | list[MCPToolCall] | None = None
     integration_test_tool: MCPToolCall | list[MCPToolCall] | None = None
-    agent_tools: list[str] | None = None
-    system_prompt: str | None = None
+    agent_config: BaseAgentConfig | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
 
+    def __init__(self, **data: Any) -> None:
+        """Initialize LegacyTask with deprecation warning."""
+        import warnings
+
+        warnings.warn(
+            "LegacyTask is deprecated in v0.5.0 and will be removed in v0.6.0 "
+            "(no earlier than March 1st, 2026). "
+            "Use Task.from_v4() for quick conversion, or migrate to @env.scenario(). "
+            "See https://docs.hud.ai/migration for details.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(**data)
+
     @field_validator("mcp_config", "metadata", mode="before")
     @classmethod
     def parse_json_strings(cls, v: Any) -> Any:
@@ -60,6 +155,25 @@ class Task(BaseModel):
                 raise HudConfigError(f"Invalid JSON string: {e}") from e
         return v
 
+    @field_validator("agent_config", mode="before")
+    @classmethod
+    def parse_agent_config(cls, v: Any) -> BaseAgentConfig | None:
+        """Parse agent_config into BaseAgentConfig."""
+        if v is None:
+            return None
+        if isinstance(v, BaseAgentConfig):
+            return v
+        if isinstance(v, str):
+            try:
+                v = json.loads(v)
+            except json.JSONDecodeError as e:
+                from hud.shared.exceptions import HudConfigError
+
+                raise HudConfigError(f"Invalid JSON string for agent_config: {e}") from e
+        if isinstance(v, dict):
+            return BaseAgentConfig(**v)
+        return v
+
     @field_validator("setup_tool", "evaluate_tool", "integration_test_tool", mode="before")
     @classmethod
     def convert_dict_to_tool_call(cls, v: Any, info: Any) -> Any:
@@ -98,44 +212,21 @@ class Task(BaseModel):
     @classmethod
     def resolve_env_vars(cls, v: dict[str, Any]) -> dict[str, Any]:
         """
-        Automatically resolve environment variables in mcp_config using Template.
+        Automatically resolve environment variables in mcp_config.
 
         Supports ${VAR_NAME} syntax with variable substitution from
-        System environment variables (including HUD_API_KEY, etc.)
+        system environment variables and settings (including HUD_API_KEY, etc.)
 
         Missing variables resolve to empty strings.
         """
-        import os
-
-        # Start with current environment variables
-        mapping = dict(os.environ)
-        # Include settings (from process env, project .env, and user .env)
-        settings_dict = settings.model_dump()
-        mapping.update(settings_dict)
-        # Add UPPERCASE aliases for settings keys
-        for _key, _val in settings_dict.items():
-            with contextlib.suppress(Exception):
-                mapping[_key.upper()] = _val
-
-        if settings.api_key:
-            mapping["HUD_API_KEY"] = settings.api_key
-        else:
-            logger.error("HUD_API_KEY is not set, tracing and remote training will not work")
-
-        def substitute_in_value(obj: Any) -> Any:
-            """Recursively substitute variables in nested structures."""
-            if isinstance(obj, str):
-                # Use Template's substitute with defaultdict - missing vars become empty strings
-                safe_mapping = defaultdict(str, mapping)
-                return Template(obj).substitute(safe_mapping)
-            elif isinstance(obj, dict):
-                return {k: substitute_in_value(v) for k, v in obj.items()}
-            elif isinstance(obj, list):
-                return [substitute_in_value(item) for item in obj]
-            else:
-                return obj
+        # Warn once if HUD_API_KEY is not set
+        if not settings.api_key:
+            global _missing_api_key_error_logged
+            if not _missing_api_key_error_logged:
+                logger.error("HUD_API_KEY is not set, tracing and remote training will not work")
+                _missing_api_key_error_logged = True
 
-        return substitute_in_value(v)
+        return _resolve_env_vars(v)
 
 
 class MCPToolCall(CallToolRequestParams):
@@ -164,7 +255,9 @@ class MCPToolCall(CallToolRequestParams):
 
 
 class MCPToolResult(CallToolResult):
-    """A tool result."""
+    """A tool result with optional call_id for correlation."""
+
+    call_id: str | None = None  # For correlating with provider-specific tool call IDs
 
     def _get_content_summary(self) -> str:
         """Extract a summary of the content."""
@@ -216,7 +309,7 @@ class AgentResponse(BaseModel):
     tool_calls: list[MCPToolCall] = Field(default_factory=list)
     done: bool = Field(default=False)
 
-    # --- TELEMETRY [hud.so] ---
+    # --- TELEMETRY [hud.ai] ---
     # Responses
     content: str | None = Field(default=None)
     reasoning: str | None = Field(default=None)
@@ -267,6 +360,27 @@ class TraceStep(BaseModel):
     model_config = ConfigDict(populate_by_name=True, extra="allow")
 
 
+class HudSpan(BaseModel):
+    """A telemetry span ready for export to HUD API."""
+
+    name: str
+    trace_id: str = Field(pattern=r"^[0-9a-fA-F]{32}$")
+    span_id: str = Field(pattern=r"^[0-9a-fA-F]{16}$")
+    parent_span_id: str | None = Field(default=None, pattern=r"^[0-9a-fA-F]{16}$")
+
+    start_time: str  # ISO format
+    end_time: str  # ISO format
+
+    status_code: str  # "UNSET", "OK", "ERROR"
+    status_message: str | None = None
+
+    attributes: TraceStep
+    exceptions: list[dict[str, Any]] | None = None
+    internal_type: str | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+
 class Trace(BaseModel):
     """Unified result from agent execution (task or prompt).
 
@@ -286,7 +400,7 @@ class Trace(BaseModel):
     isError: bool = Field(default=False)
 
     # Metadata
-    task: Task | None = Field(default=None)
+    task: LegacyTask | None = Field(default=None)
 
     # Trace
     trace: list[TraceStep] = Field(default_factory=list)
@@ -302,26 +416,22 @@ class Trace(BaseModel):
     def append(self, step: TraceStep) -> None:
         self.trace.append(step)
 
-    def populate_from_context(self) -> None:
-        """Populate trace steps from the current trace context if available.
-
-        This checks if we're executing within a hud.trace() context and
-        automatically populates the trace field with collected steps.
-        """
-        from hud.otel.context import get_current_task_run_id
-        from hud.telemetry.replay import get_trace
 
-        task_run_id = get_current_task_run_id()
-        if task_run_id:
-            collected_trace = get_trace(task_run_id)
-            if collected_trace:
-                self.trace = collected_trace.trace
+# Re-export Task for backwards compatibility (after module defs to avoid circular import)
+from hud.eval.task import Task  # noqa: E402
 
+# Type alias for functions that accept v5 Task, v4 LegacyTask, or raw dicts
+TaskInput = Task | LegacyTask | dict[str, Any]
 
 __all__ = [
     "AgentResponse",
+    "AgentType",
+    "HudSpan",
+    "LegacyTask",
     "MCPToolCall",
     "MCPToolResult",
+    "Task",
+    "TaskInput",
     "Trace",
     "TraceStep",
 ]

hud/utils/__init__.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 from .hud_console import HUDConsole, hud_console
 from .telemetry import stream
+from .types import with_signature
 
 __all__ = [
     "HUDConsole",
     "hud_console",
     "stream",
+    "with_signature",
 ]

hud/utils/env.py

@@ -0,0 +1,67 @@
+"""Environment variable resolution utilities."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from collections import defaultdict
+from string import Template
+from typing import TYPE_CHECKING, Any
+
+from hud.settings import settings
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+def resolve_env_vars(obj: Any, extra_mapping: Mapping[str, Any] | None = None) -> Any:
+    """Recursively resolve ${VAR_NAME} placeholders in strings.
+
+    Uses Python's string.Template for substitution. Sources values from:
+    1. os.environ
+    2. hud.settings (loads from project .env and ~/.hud/.env)
+    3. Optional extra_mapping parameter
+
+    Uppercase aliases are automatically added for settings keys,
+    so both ${api_key} and ${API_KEY} work.
+
+    Missing variables resolve to empty strings.
+
+    Args:
+        obj: The object to resolve (string, dict, list, or other).
+        extra_mapping: Optional additional key-value pairs to include.
+
+    Returns:
+        The object with all ${VAR_NAME} placeholders resolved.
+
+    Example:
+        >>> resolve_env_vars({"key": "${MY_VAR}"})
+        {'key': 'resolved_value'}
+    """
+    # Build mapping from environment and settings
+    mapping: dict[str, Any] = dict(os.environ)
+    settings_dict = settings.model_dump()
+    mapping.update(settings_dict)
+
+    # Add UPPERCASE aliases for settings keys
+    for key, val in settings_dict.items():
+        with contextlib.suppress(Exception):
+            mapping[key.upper()] = val
+
+    if settings.api_key:
+        mapping["HUD_API_KEY"] = settings.api_key
+
+    if extra_mapping:
+        mapping.update(extra_mapping)
+
+    def substitute(value: Any) -> Any:
+        if isinstance(value, str):
+            safe_mapping = defaultdict(str, mapping)
+            return Template(value).substitute(safe_mapping)
+        elif isinstance(value, dict):
+            return {k: substitute(v) for k, v in value.items()}
+        elif isinstance(value, list):
+            return [substitute(item) for item in value]
+        return value
+
+    return substitute(obj)