hud-python 0.4.51__py3-none-any.whl → 0.4.53__py3-none-any.whl

hud/telemetry/tests/test_trace.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
 
-from hud.telemetry.trace import trace
+import pytest
+
+from hud.telemetry.trace import Trace, trace
 
 
 class TestTraceAPI:
@@ -19,11 +21,11 @@ class TestTraceAPI:
             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"
+            mock_otel_trace.return_value.__enter__.return_value = "1234567890"
 
             with trace("test-trace") as task_run_id:
                 # Should use placeholder ID for custom backends
-                assert task_run_id.id == "custom-otlp-trace"
+                assert len(task_run_id.id) == 36
 
     def test_trace_with_enabled_telemetry_and_api_key(self):
         """Test trace behavior when telemetry is enabled with API key."""
@@ -59,5 +61,181 @@ class TestTraceAPI:
             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.id == "custom-otlp-trace"
+                # In absence of HUD API key, ID should still be a string
+                assert isinstance(task_run_id.id, str)
+
+    def test_trace_with_job_id(self):
+        """Test trace with job_id parameter."""
+        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,
+            trace("test-trace", job_id="job-123") as trace_obj,
+        ):
+            assert trace_obj.job_id == "job-123"
+
+            # Check OtelTrace was called with job_id
+            call_kwargs = mock_otel_trace.call_args[1]
+            assert call_kwargs["job_id"] == "job-123"
+
+    def test_trace_with_task_id(self):
+        """Test trace with task_id parameter."""
+        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"),
+            trace("test-trace", task_id="task-456") as trace_obj,
+        ):
+            assert trace_obj.task_id == "task-456"
+
+    def test_trace_with_attributes(self):
+        """Test trace with custom attributes."""
+        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,
+            trace("test-trace", attrs={"custom": "value"}),
+        ):
+            # Check OtelTrace was called with attributes
+            call_kwargs = mock_otel_trace.call_args[1]
+            assert call_kwargs["attributes"] == {"custom": "value"}
+
+    def test_trace_non_root(self):
+        """Test trace with root=False."""
+        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,
+            trace("test-trace", root=False),
+        ):
+            # Check OtelTrace was called with is_root=False
+            call_kwargs = mock_otel_trace.call_args[1]
+            assert call_kwargs["is_root"] is False
+
+
+class TestTraceClass:
+    """Tests for Trace class."""
+
+    def test_trace_initialization(self):
+        """Test Trace initialization."""
+        trace_obj = Trace(
+            trace_id="test-id",
+            name="Test Trace",
+            job_id="job-123",
+            task_id="task-456",
+        )
+
+        assert trace_obj.id == "test-id"
+        assert trace_obj.name == "Test Trace"
+        assert trace_obj.job_id == "job-123"
+        assert trace_obj.task_id == "task-456"
+        assert trace_obj.created_at is not None
+
+    @pytest.mark.asyncio
+    async def test_trace_log(self):
+        """Test Trace async log method."""
+        trace_obj = Trace("test-id", "Test")
+
+        with (
+            patch("hud.telemetry.trace.settings") as mock_settings,
+            patch("hud.telemetry.trace.make_request", new_callable=AsyncMock) as mock_request,
+        ):
+            mock_settings.telemetry_enabled = True
+            mock_settings.api_key = "test-key"
+            mock_settings.hud_telemetry_url = "https://test.com"
+
+            await trace_obj.log({"metric": 1.0})
+
+            mock_request.assert_called_once()
+            call_kwargs = mock_request.call_args[1]
+            assert call_kwargs["json"]["metrics"] == {"metric": 1.0}
+
+    @pytest.mark.asyncio
+    async def test_trace_log_telemetry_disabled(self):
+        """Test Trace log when telemetry is disabled."""
+        trace_obj = Trace("test-id", "Test")
+
+        with (
+            patch("hud.telemetry.trace.settings") as mock_settings,
+            patch("hud.telemetry.trace.make_request", new_callable=AsyncMock) as mock_request,
+        ):
+            mock_settings.telemetry_enabled = False
+
+            await trace_obj.log({"metric": 1.0})
+
+            mock_request.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_trace_log_error(self):
+        """Test Trace log handles errors gracefully."""
+        trace_obj = Trace("test-id", "Test")
+
+        with (
+            patch("hud.telemetry.trace.settings") as mock_settings,
+            patch("hud.telemetry.trace.make_request", new_callable=AsyncMock) as mock_request,
+        ):
+            mock_settings.telemetry_enabled = True
+            mock_settings.api_key = "test-key"
+            mock_settings.hud_telemetry_url = "https://test.com"
+            mock_request.side_effect = Exception("Network error")
+
+            # Should not raise
+            await trace_obj.log({"metric": 1.0})
+
+    def test_trace_log_sync(self):
+        """Test Trace sync log method."""
+        trace_obj = Trace("test-id", "Test")
+
+        with (
+            patch("hud.telemetry.trace.settings") as mock_settings,
+            patch("hud.telemetry.trace.make_request_sync") as mock_request,
+        ):
+            mock_settings.telemetry_enabled = True
+            mock_settings.api_key = "test-key"
+            mock_settings.hud_telemetry_url = "https://test.com"
+
+            trace_obj.log_sync({"metric": 1.0})
+
+            mock_request.assert_called_once()
+
+    def test_trace_log_sync_telemetry_disabled(self):
+        """Test Trace sync log when telemetry is disabled."""
+        trace_obj = Trace("test-id", "Test")
+
+        with (
+            patch("hud.telemetry.trace.settings") as mock_settings,
+            patch("hud.telemetry.trace.make_request_sync") as mock_request,
+        ):
+            mock_settings.telemetry_enabled = False
+
+            trace_obj.log_sync({"metric": 1.0})
+
+            mock_request.assert_not_called()
+
+    def test_trace_log_sync_error(self):
+        """Test Trace sync log handles errors gracefully."""
+        trace_obj = Trace("test-id", "Test")
+
+        with (
+            patch("hud.telemetry.trace.settings") as mock_settings,
+            patch("hud.telemetry.trace.make_request_sync") as mock_request,
+        ):
+            mock_settings.telemetry_enabled = True
+            mock_settings.api_key = "test-key"
+            mock_settings.hud_telemetry_url = "https://test.com"
+            mock_request.side_effect = Exception("Network error")
+
+            # Should not raise
+            trace_obj.log_sync({"metric": 1.0})
+
+    def test_trace_repr(self):
+        """Test Trace __repr__."""
+        trace_obj = Trace("test-id", "Test Trace")
+
+        repr_str = repr(trace_obj)
+        assert "test-id" in repr_str
+        assert "Test Trace" in repr_str

hud/telemetry/trace.py

@@ -94,7 +94,7 @@ def trace(
     job_id: str | None = None,
     task_id: str | None = None,
 ) -> Generator[Trace, None, None]:
-    """Start a HUD trace context.
+    """Start a HUD trace context for telemetry tracking.
 
     A unique task_run_id is automatically generated for each trace.
 
@@ -108,22 +108,21 @@ def trace(
     Yields:
         Trace: The trace object with logging capabilities
 
-    Usage:
-        import hud
-
-        # Basic usage
-        with hud.trace("My Task") as trace:
-            # Your code here
-            trace.log_sync({"step": 1, "progress": 0.5})
-
-        # Async logging
-        async with hud.trace("Async Task") as trace:
-            await trace.log({"loss": 0.23, "accuracy": 0.95})
-
-        # With job association
-        with hud.job("Training Run") as job:
-            with hud.trace("Epoch 1", job_id=job.id) as trace:
-                trace.log_sync({"epoch": 1, "loss": 0.5})
+    Example:
+        >>> import hud
+        >>> # Synchronous code
+        >>> with hud.trace("My Task") as trace:
+        ...     do_work()
+        ...     trace.log_sync({"step": 1, "progress": 0.5})
+        >>> # For async code with HIGH CONCURRENCY (200+ tasks), use async_trace
+        >>> async with hud.async_trace("My Async Task") as trace:
+        ...     await do_async_work()
+        ...     await trace.log({"loss": 0.23, "accuracy": 0.95})
+
+    Note:
+        For simple async code (< 30 parallel tasks), this context manager works fine
+        with `async with`. Use `hud.async_trace()` only for high-concurrency scenarios
+        (200+ parallel tasks) where event loop blocking becomes an issue.
     """
     # Ensure telemetry is configured
     configure_telemetry()

hud/tools/computer/qwen.py

@@ -424,7 +424,10 @@ coordinate on the screen.
                 # Rescale screenshot if requested
                 screenshot_base64 = await self._rescale_screenshot(screenshot_base64)
                 result = ContentResult(
-                    output=result.output, error=result.error, base64_image=screenshot_base64
+                    # note: we suppress the output since it's not useful
+                    output="",
+                    error=result.error,
+                    base64_image=screenshot_base64,
                 )
 
         # Convert to content blocks

hud/tools/computer/settings.py

@@ -63,12 +63,12 @@ class ComputerSettings(BaseSettings):
     )
 
     QWEN_COMPUTER_WIDTH: int = Field(
-        default=1920,
+        default=700,
         description="Width of the display to use for the Qwen computer tools",
         validation_alias="QWEN_COMPUTER_WIDTH",
     )
     QWEN_COMPUTER_HEIGHT: int = Field(
-        default=1080,
+        default=448,
         description="Height of the display to use for the Qwen computer tools",
         validation_alias="QWEN_COMPUTER_HEIGHT",
     )

hud/tools/executors/base.py

@@ -280,7 +280,7 @@ class BaseExecutor:
 
     # ===== Utility Actions =====
 
-    async def wait(self, time: int) -> ContentResult:
+    async def wait(self, time: int, take_screenshot: bool = True) -> ContentResult:
         """
         Wait for specified time.
 
@@ -289,7 +289,9 @@ class BaseExecutor:
         """
         duration_seconds = time / 1000.0
         await asyncio.sleep(duration_seconds)
-        return ContentResult(output=f"Waited {time}ms")
+        # take screenshot
+        screenshot = await self.screenshot() if take_screenshot else None
+        return ContentResult(output=f"Waited {time}ms", base64_image=screenshot)
 
     async def screenshot(self) -> str | None:
         """

hud/tools/tests/test_submit.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import pytest
+from mcp.types import TextContent
+
+from hud.tools.submit import SubmitTool, get_submission, set_submission
+
+
+@pytest.fixture(autouse=True)
+def reset_submission():
+    """Reset submission before each test."""
+    set_submission(None)
+    yield
+    set_submission(None)
+
+
+def test_set_and_get_submission():
+    """Test setting and getting submission value."""
+    assert get_submission() is None
+
+    set_submission("test value")
+    assert get_submission() == "test value"
+
+    set_submission("another value")
+    assert get_submission() == "another value"
+
+    set_submission(None)
+    assert get_submission() is None
+
+
+@pytest.mark.asyncio
+async def test_submit_tool_with_response():
+    """Test SubmitTool with a response string."""
+    tool = SubmitTool()
+
+    result = await tool(response="Test response")
+
+    assert get_submission() == "Test response"
+    assert len(result) == 1
+    assert isinstance(result[0], TextContent)
+    assert result[0].text == "Test response"
+
+
+@pytest.mark.asyncio
+async def test_submit_tool_with_none():
+    """Test SubmitTool with None response."""
+    tool = SubmitTool()
+
+    result = await tool(response=None)
+
+    assert get_submission() is None
+    assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_submit_tool_with_empty_string():
+    """Test SubmitTool with empty string."""
+    tool = SubmitTool()
+
+    result = await tool(response="")
+
+    assert get_submission() == ""
+    assert len(result) == 0
+
+
+@pytest.mark.asyncio
+async def test_submit_tool_overwrite():
+    """Test that submitting overwrites previous submission."""
+    tool = SubmitTool()
+
+    await tool(response="First submission")
+    assert get_submission() == "First submission"
+
+    await tool(response="Second submission")
+    assert get_submission() == "Second submission"
+
+
+@pytest.mark.asyncio
+async def test_submit_tool_properties():
+    """Test SubmitTool properties."""
+    tool = SubmitTool()
+
+    assert tool.name == "response"
+    assert tool.title == "Submit Tool"
+    assert "final response" in tool.description.lower()

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/types.py

@@ -17,6 +17,9 @@ 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):
     """
@@ -119,7 +122,10 @@ class Task(BaseModel):
         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")
+            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
 
         def substitute_in_value(obj: Any) -> Any:
             """Recursively substitute variables in nested structures."""

hud/utils/agent_factories.py

@@ -36,9 +36,7 @@ def create_openai_agent(**kwargs: Any) -> GenericOpenAIChatAgent:
     api_key = kwargs.pop("api_key", None)
     base_url = kwargs.pop("base_url", None)
 
-    openai_client = AsyncOpenAI(api_key=api_key, base_url=base_url)
-
-    return GenericOpenAIChatAgent(openai_client=openai_client, **kwargs)
+    return GenericOpenAIChatAgent(api_key=api_key, base_url=base_url, **kwargs)
 
 
 def create_grounded_agent(**kwargs: Any) -> GroundedOpenAIChatAgent:

hud/utils/mcp.py

@@ -46,7 +46,7 @@ def setup_hud_telemetry(
         The auto-created trace context manager if one was created, None otherwise.
         Caller is responsible for exiting the context manager.
     """
-    if not mcp_config:
+    if mcp_config is None:
         raise ValueError("Please run initialize() before setting up client-side telemetry")
 
     # Check if there are any HUD servers to setup telemetry for