hud-python 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

hud/utils/progress.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+
+
+class StepProgressTracker:
+    """
+    Tracks progress across potentially parallel async tasks based on steps completed.
+    Provides estimates assuming tasks run up to max_steps_per_task.
+    """
+
+    def __init__(self, total_tasks: int, max_steps_per_task: int) -> None:
+        """
+        Initialize the StepProgressTracker.
+
+        Args:
+            total_tasks: The total number of tasks to track.
+            max_steps_per_task: The maximum number of steps per task.
+
+        Raises:
+            ValueError: If total_tasks or max_steps_per_task is not positive.
+        """
+        if total_tasks <= 0:
+            raise ValueError("total_tasks must be positive")
+        if max_steps_per_task <= 0:
+            raise ValueError("max_steps_per_task must be positive")
+
+        self.total_tasks = total_tasks
+        self.max_steps_per_task = max_steps_per_task
+        self.total_potential_steps = total_tasks * max_steps_per_task
+
+        # Use asyncio.Lock for potentially concurrent updates/reads if needed,
+        # but start without for simplicity in single-threaded asyncio.
+        # self._lock = asyncio.Lock()
+        self._task_steps: dict[str, int] = defaultdict(int)
+        self._finished_tasks: dict[str, bool] = defaultdict(bool)
+        self._tasks_started = 0
+        self._tasks_finished = 0
+
+        self.start_time: float | None = None
+        self.current_total_steps = 0
+
+    def start_task(self, task_id: str) -> None:
+        # async with self._lock: # If using lock
+        if self.start_time is None:
+            self.start_time = time.monotonic()
+        self._task_steps[task_id] = 0
+        self._finished_tasks[task_id] = False
+        self._tasks_started += 1
+
+    def increment_step(self, task_id: str) -> None:
+        # async with self._lock:
+        if (
+            not self._finished_tasks[task_id]
+            and self._task_steps[task_id] < self.max_steps_per_task
+        ):
+            self._task_steps[task_id] += 1
+            # Update overall progress immediately
+            self._update_total_steps()
+
+    def finish_task(self, task_id: str) -> None:
+        # async with self._lock:
+        if not self._finished_tasks[task_id]:
+            # For calculation, consider a finished task as having completed max steps
+            self._task_steps[task_id] = self.max_steps_per_task
+            self._finished_tasks[task_id] = True
+            self._tasks_finished += 1
+            # Update overall progress
+            self._update_total_steps()
+
+    def _update_total_steps(self) -> None:
+        # This could be expensive if called extremely frequently.
+        # Called after increment or finish.
+        # async with self._lock:
+        self.current_total_steps = sum(self._task_steps.values())
+
+    def get_progress(self) -> tuple[int, int, float]:
+        """Returns (current_steps, total_potential_steps, percentage)."""
+        # async with self._lock:
+        # Recalculate here for safety, though _update_total_steps should keep it current
+        # current_steps = sum(self._task_steps.values())
+        current_steps = self.current_total_steps
+
+        percentage = 0.0
+        if self.total_potential_steps > 0:
+            percentage = (current_steps / self.total_potential_steps) * 100
+        return current_steps, self.total_potential_steps, percentage
+
+    def get_stats(self) -> tuple[float, float | None]:
+        """Returns (rate_steps_per_minute, eta_seconds_upper_bound)."""
+        # async with self._lock:
+        if self.start_time is None or self._tasks_started == 0:
+            return 0.0, None  # No rate or ETA yet
+
+        elapsed_time = time.monotonic() - self.start_time
+        current_steps = self.current_total_steps
+
+        rate_sec = 0.0
+        if elapsed_time > 0:
+            rate_sec = current_steps / elapsed_time
+
+        rate_min = rate_sec * 60  # Convert rate to steps per minute
+
+        eta = None
+        # ETA calculation still uses rate_sec (steps/second) for time estimation in seconds
+        if rate_sec > 0:
+            remaining_steps = self.total_potential_steps - current_steps
+            eta = remaining_steps / rate_sec if remaining_steps > 0 else 0.0
+
+        return rate_min, eta  # Return rate in steps/min
+
+    def is_finished(self) -> bool:
+        # async with self._lock:
+        return self._tasks_finished >= self.total_tasks
+
+    def display(self, bar_length: int = 40) -> str:
+        """Generates a progress string similar to tqdm."""
+        current_steps, total_steps, percentage = self.get_progress()
+        rate_min, eta = self.get_stats()  # Rate is now per minute
+
+        # Ensure valid values for display
+        current_steps = min(current_steps, total_steps)
+        percentage = max(0.0, min(100.0, percentage))
+
+        filled_length = int(bar_length * current_steps // total_steps) if total_steps else 0
+        bar = "█" * filled_length + "-" * (bar_length - filled_length)
+
+        # Format time
+        elapsed_str = "0:00"
+        eta_str = "??:??"
+        if self.start_time:
+            elapsed_seconds = int(time.monotonic() - self.start_time)
+            elapsed_str = f"{elapsed_seconds // 60}:{elapsed_seconds % 60:02d}"
+            if eta is not None:
+                eta_seconds = int(eta)
+                eta_str = f"{eta_seconds // 60}:{eta_seconds % 60:02d}"
+            elif self.is_finished():
+                eta_str = "0:00"
+
+        # Update rate string format
+        rate_str = f"{rate_min:.1f} steps/min" if rate_min > 0 else "?? steps/min"
+
+        # Format steps - use K/M for large numbers if desired, keep simple for now
+        steps_str = f"{current_steps}/{total_steps}"
+
+        # tasks_str = f" {self._tasks_finished}/{self.total_tasks} tasks" # Optional tasks counter
+
+        return f"{percentage:3.0f}%|{bar}| {steps_str} [{elapsed_str}<{eta_str}, {rate_str}]"

hud/utils/telemetry.py

@@ -4,12 +4,11 @@ import logging
 
 logger = logging.getLogger(__name__)
 
-def stream(live_url: str | None = None) -> str:
+
+def stream(live_url: str) -> str:
     """
     Display a stream in the HUD system.
     """
-    if live_url is None:
-        raise ValueError("live_url cannot be None")
     from IPython.display import HTML, display
 
     html_content = f"""
@@ -24,44 +23,44 @@ def stream(live_url: str | None = None) -> str:
         display(HTML(html_content))
     except Exception as e:
         logger.warning(e)
-    
+
     return html_content
 
 
 def display_screenshot(base64_image: str, width: int = 960, height: int = 540) -> str:
     """
     Display a base64-encoded screenshot image.
-    
+
     Args:
         base64_image: Base64-encoded image string (without the data URI prefix)
         width: Display width in pixels
         height: Display height in pixels
-        
+
     Returns:
         The HTML string used to display the image
-        
+
     Note:
         This function will both display the image in IPython environments
         and return the HTML string for other contexts.
     """
     from IPython.display import HTML, display
-    
+
     # Ensure the base64 image doesn't already have the data URI prefix
     if base64_image.startswith("data:image"):
         img_src = base64_image
     else:
         img_src = f"data:image/png;base64,{base64_image}"
-    
+
     html_content = f"""
     <div style="width: {width}px; height: {height}px; overflow: hidden; margin: 10px 0; border: 1px solid #ddd;">
         <img src="{img_src}" style="max-width: 100%; max-height: 100%;">
     </div>
     """  # noqa: E501
-    
+
     # Display in IPython environments
     try:
         display(HTML(html_content))
     except Exception as e:
         logger.warning(e)
-    
+
     return html_content

hud/utils/tests/test_common.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import io
+import tarfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+from hud.utils.common import directory_to_tar_bytes, get_gym_id
+
+if TYPE_CHECKING:
+    import pytest_mock
+
+
+def test_directory_to_tar_bytes(tmpdir_factory: pytest.TempdirFactory):
+    """Test that a directory can be converted to a tar bytes object."""
+    temp_dir = tmpdir_factory.mktemp("test_dir")
+    temp_dir_path = Path(temp_dir)
+
+    (temp_dir_path / "test.txt").write_text("test content")
+
+    nested_dir = temp_dir_path / "nested"
+    nested_dir.mkdir(exist_ok=True)
+    (nested_dir / "file.txt").write_text("nested content")
+
+    tar_bytes = directory_to_tar_bytes(temp_dir_path)
+    assert tar_bytes is not None
+    assert len(tar_bytes) > 0
+
+    with tarfile.open(fileobj=io.BytesIO(tar_bytes), mode="r:*") as tar:
+        members = tar.getmembers()
+        member_names = {m.name for m in members}
+
+        assert "test.txt" in member_names
+        assert "nested/file.txt" in member_names
+
+        test_content = tar.extractfile("test.txt")
+        assert test_content is not None
+        assert test_content.read().decode() == "test content"
+
+        nested_content = tar.extractfile("nested/file.txt")
+        assert nested_content is not None
+        assert nested_content.read().decode() == "nested content"
+
+
+@pytest.mark.asyncio
+async def test_get_gym_id(mocker: pytest_mock.MockerFixture):
+    """Test that the gym ID can be retrieved."""
+    mocker.patch("hud.utils.common.make_request", return_value={"id": "test_gym_id"})
+    gym_id = await get_gym_id("test_gym")
+    assert gym_id == "test_gym_id"

hud/utils/tests/test_config.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import pytest
+
+from hud.utils.common import FunctionConfig
+from hud.utils.config import (
+    _is_list_of_configs,
+    _is_valid_python_name,
+    _split_and_validate_path,
+    _validate_hud_config,
+    expand_config,
+)
+
+
+@pytest.mark.parametrize(
+    "config, expected",
+    [
+        ("test", [{"function": "test", "args": [], "id": None}]),
+        (("test",), [{"function": "test", "args": [], "id": None}]),
+        (
+            [FunctionConfig(function="test", args=[])],
+            [{"function": "test", "args": [], "id": None}],
+        ),
+        ({"function": "test", "args": []}, [{"function": "test", "args": [], "id": None}]),
+        (
+            {"function": "test", "args": ["arg1"]},
+            [{"function": "test", "args": ["arg1"], "id": None}],
+        ),
+        (
+            {"function": "test", "args": ["arg1"], "id": "test_id"},
+            [{"function": "test", "args": ["arg1"], "id": "test_id"}],
+        ),
+        (("test", "arg1", "arg2"), [{"function": "test", "args": ["arg1", "arg2"], "id": None}]),
+    ],
+)
+def test_expand_config(config, expected):
+    result = expand_config(config)
+    assert len(result) == len(expected)
+    for i, item in enumerate(result):
+        assert item.function == expected[i]["function"]
+        assert item.args == expected[i]["args"]
+        assert item.id == expected[i]["id"]
+
+
+@pytest.mark.parametrize(
+    "name, expected",
+    [
+        ("valid_name", True),
+        ("ValidName", True),
+        ("valid_name_123", True),
+        ("_valid_name", True),
+        ("123_invalid", False),
+        ("invalid-name", False),
+        ("", False),
+    ],
+)
+def test_is_valid_python_name(name, expected):
+    assert _is_valid_python_name(name) == expected
+
+
+def test_validate_hud_config_valid():
+    config = {"function": "test.func", "args": ["arg1", "arg2"]}
+    result = _validate_hud_config(config)
+    assert result.function == "test.func"
+    assert result.args == ["arg1", "arg2"]
+    assert result.id is None
+
+    # Test with single arg (not in a list)
+    config = {"function": "test.func", "args": "arg1"}
+    result = _validate_hud_config(config)
+    assert result.function == "test.func"
+    assert result.args == ["arg1"]
+
+    # Test with ID
+    config = {"function": "test.func", "args": [], "id": "test_id"}
+    result = _validate_hud_config(config)
+    assert result.id == "test_id"
+
+
+def test_validate_hud_config_invalid():
+    with pytest.raises(ValueError, match="function must be a string"):
+        _validate_hud_config({"args": []})
+
+    with pytest.raises(ValueError, match="function must be a string"):
+        _validate_hud_config({"function": 123, "args": []})
+
+
+def test_split_and_validate_path_valid():
+    # none should raise
+    _split_and_validate_path("module.submodule.function")
+    _split_and_validate_path("function")
+    _split_and_validate_path("Module_123.function_456")
+
+
+def test_split_and_validate_path_invalid():
+    with pytest.raises(ValueError, match="Invalid Python identifier in path"):
+        _split_and_validate_path("invalid-module.function")
+
+
+def test_is_list_of_configs():
+    valid_list = [
+        FunctionConfig(function="test1", args=[]),
+        FunctionConfig(function="test2", args=["arg1"]),
+    ]
+    assert _is_list_of_configs(valid_list) is True
+
+    # Empty list
+    assert _is_list_of_configs([]) is True
+
+    # Invalid: not a list
+    assert _is_list_of_configs("not_a_list") is False
+
+    # Invalid: list with non-FunctionConfig items
+    invalid_list = [FunctionConfig(function="test", args=[]), "not_a_function_config"]
+    assert _is_list_of_configs(invalid_list) is False
+
+
+def test_expand_config_errors():
+    with pytest.raises(ValueError):
+        empty_tuple = ()
+        expand_config(empty_tuple)  # type: ignore
+
+    with pytest.raises(ValueError):
+        invalid_tuple = (123, "arg1")
+        expand_config(invalid_tuple)  # type: ignore
+
+    with pytest.raises(ValueError, match="Unknown configuration type"):
+        invalid_value = 123
+        expand_config(invalid_value)  # type: ignore

hud/utils/tests/test_progress.py

@@ -0,0 +1,225 @@
+"""Tests for the progress tracking utilities."""
+
+from __future__ import annotations
+
+import pytest
+
+from hud.utils.progress import StepProgressTracker
+
+
+@pytest.fixture
+def tracker():
+    return StepProgressTracker(total_tasks=2, max_steps_per_task=10)
+
+
+def test_invalid_inputs_init():
+    with pytest.raises(ValueError, match="total_tasks must be positive"):
+        StepProgressTracker(total_tasks=0, max_steps_per_task=10)
+
+    with pytest.raises(ValueError, match="max_steps_per_task must be positive"):
+        StepProgressTracker(total_tasks=5, max_steps_per_task=0)
+
+
+def test_start_task(tracker):
+    assert tracker.start_time is None
+    assert tracker._tasks_started == 0
+
+    tracker.start_task("task1")
+
+    assert tracker.start_time is not None
+    assert tracker._tasks_started == 1
+    assert tracker._task_steps["task1"] == 0
+    assert not tracker._finished_tasks["task1"]
+
+    tracker.start_task("task2")
+    assert tracker._tasks_started == 2
+    assert tracker._task_steps["task2"] == 0
+    assert not tracker._finished_tasks["task2"]
+
+
+def test_increment_step(tracker):
+    tracker.start_task("task1")
+    assert tracker.current_total_steps == 0
+
+    tracker.increment_step("task1")
+    assert tracker._task_steps["task1"] == 1
+    assert tracker.current_total_steps == 1
+
+    tracker.increment_step("task1")
+    tracker.increment_step("task1")
+    assert tracker._task_steps["task1"] == 3
+    assert tracker.current_total_steps == 3
+
+    tracker.start_task("task2")
+    tracker.increment_step("task2")
+    assert tracker._task_steps["task2"] == 1
+    assert tracker.current_total_steps == 4
+
+    tracker.finish_task("task1")
+    initial_steps = tracker.current_total_steps
+    tracker.increment_step("task1")
+    assert tracker.current_total_steps == initial_steps
+
+    for _ in range(15):
+        tracker.increment_step("task2")
+    assert tracker._task_steps["task2"] <= tracker.max_steps_per_task
+
+
+def test_finish_task(tracker):
+    tracker.start_task("task1")
+    tracker.start_task("task2")
+
+    tracker.increment_step("task1")
+    tracker.increment_step("task1")
+    initial_steps = tracker._task_steps["task1"]
+
+    tracker.finish_task("task1")
+
+    assert tracker._finished_tasks["task1"]
+    assert tracker._tasks_finished == 1
+    assert tracker._task_steps["task1"] == tracker.max_steps_per_task
+    assert tracker.current_total_steps > initial_steps
+
+    current_steps = tracker.current_total_steps
+    tracker.finish_task("task1")
+    assert tracker._tasks_finished == 1
+    assert tracker.current_total_steps == current_steps
+
+
+def test_get_progress(tracker):
+    steps, total, percentage = tracker.get_progress()
+    assert steps == 0
+    assert total == tracker.total_potential_steps
+    assert percentage == 0.0
+
+    tracker.start_task("task1")
+    tracker.increment_step("task1")
+    steps, total, percentage = tracker.get_progress()
+    assert steps == 1
+    assert total == tracker.total_potential_steps
+    assert percentage == (1 / tracker.total_potential_steps) * 100
+
+    tracker.finish_task("task1")
+    steps, total, percentage = tracker.get_progress()
+    assert steps == tracker.max_steps_per_task
+    assert total == tracker.total_potential_steps
+    assert percentage == (tracker.max_steps_per_task / tracker.total_potential_steps) * 100
+
+    tracker.start_task("task2")
+    tracker.finish_task("task2")
+    steps, total, percentage = tracker.get_progress()
+    assert steps == tracker.total_potential_steps
+    assert percentage == 100.0
+
+
+def test_get_stats_no_progress(tracker, mocker):
+    rate, eta = tracker.get_stats()
+    assert rate == 0.0
+    assert eta is None
+
+    mocker.patch("time.monotonic", return_value=100.0)
+    tracker.start_task("task1")
+
+    mocker.patch("time.monotonic", return_value=100.0)
+    rate, eta = tracker.get_stats()
+    assert rate == 0.0
+    assert eta is None
+
+
+def test_get_stats_with_progress(mocker):
+    mock_time = mocker.patch("time.monotonic")
+    mock_time.return_value = 100.0
+
+    tracker = StepProgressTracker(total_tasks=1, max_steps_per_task=10)
+    tracker.start_task("task1")
+
+    mock_time.return_value = 160.0
+    for _ in range(5):
+        tracker.increment_step("task1")
+
+    rate, eta = tracker.get_stats()
+
+    assert rate == pytest.approx(5.0)
+    assert eta == pytest.approx(60.0)
+
+    for _ in range(5):
+        tracker.increment_step("task1")
+
+    rate, eta = tracker.get_stats()
+    assert rate == pytest.approx(10.0)
+    assert eta == pytest.approx(0.0)
+
+
+def test_is_finished(tracker):
+    assert not tracker.is_finished()
+
+    tracker.start_task("task1")
+    tracker.finish_task("task1")
+    assert not tracker.is_finished()
+
+    tracker.start_task("task2")
+    tracker.finish_task("task2")
+    assert tracker.is_finished()
+
+
+def test_display(tracker, mocker):
+    mock_time = mocker.patch("time.monotonic")
+    mock_time.return_value = 100.0
+    tracker.start_task("task1")
+
+    mock_time.return_value = 130.0
+    tracker.increment_step("task1")
+    tracker.increment_step("task1")
+
+    display_str = tracker.display()
+
+    assert "%" in display_str
+    assert "2/20" in display_str
+    assert "0:30" in display_str
+    assert "steps/min" in display_str
+
+    tracker.finish_task("task1")
+    display_str = tracker.display()
+    assert "10/20" in display_str
+
+    tracker.start_task("task2")
+    tracker.finish_task("task2")
+    display_str = tracker.display()
+    assert "100%" in display_str
+    assert "20/20" in display_str
+
+
+def test_complex_workflow():
+    tracker = StepProgressTracker(total_tasks=5, max_steps_per_task=20)
+
+    for i in range(5):
+        tracker.start_task(f"task{i}")
+
+    for _ in range(10):
+        tracker.increment_step("task0")
+
+    for _ in range(5):
+        tracker.increment_step("task1")
+
+    tracker.finish_task("task2")
+
+    for _ in range(15):
+        tracker.increment_step("task3")
+
+    tracker.finish_task("task3")
+
+    steps, total, percentage = tracker.get_progress()
+    expected_steps = 10 + 5 + 20 + 20 + 0
+    assert steps == expected_steps
+    assert total == 5 * 20
+    assert percentage == (expected_steps / total) * 100
+
+    assert tracker._tasks_finished == 2
+    assert not tracker.is_finished()
+
+    tracker.finish_task("task0")
+    tracker.finish_task("task1")
+    tracker.finish_task("task4")
+
+    assert tracker.is_finished()
+    assert tracker.get_progress()[2] == 100.0

hud/utils/tests/test_telemetry.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from hud.utils.telemetry import stream
+
+
+def test_stream():
+    html_content = stream("https://example.com")
+    assert html_content is not None
+    assert "<div style=" in html_content
+    assert 'src="https://example.com"' in html_content
+
+
+def test_display_screenshot():
+    from hud.utils.telemetry import display_screenshot
+
+    # This is a simple 1x1 transparent PNG image in base64 format
+    base64_image = (
+        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQ"
+        "AAABJRU5ErkJggg=="
+    )
+
+    html_content = display_screenshot(base64_image)
+    assert html_content is not None
+    assert "<div style=" in html_content
+    assert "width: 960px" in html_content
+    assert "height: 540px" in html_content
+    assert f"data:image/png;base64,{base64_image}" in html_content
+
+    # Test with custom dimensions
+    custom_html = display_screenshot(base64_image, width=800, height=600)
+    assert "width: 800px" in custom_html
+    assert "height: 600px" in custom_html
+
+    # Test with data URI already included
+    data_uri = f"data:image/png;base64,{base64_image}"
+    uri_html = display_screenshot(data_uri)
+    assert data_uri in uri_html

hud/utils/tests/test_version.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+
+def test_import():
+    """Test that the package can be imported."""
+    import hud
+
+    assert hud.__version__ == "0.2.3"