hud-python 0.3.1__tar.gz → 0.3.2__tar.gz

{hud_python-0.3.1 → hud_python-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hud-python
-Version: 0.3.1
+Version: 0.3.2
 Summary: SDK for the HUD platform.
 Project-URL: Homepage, https://github.com/hud-evals/hud-python
 Project-URL: Bug Tracker, https://github.com/hud-evals/hud-python/issues

{hud_python-0.3.1 → hud_python-0.3.2}/environments/README.md

@@ -19,6 +19,26 @@ The official MCP lifecycle specification is an excellent companion reference –
 
 Take the phases one at a time; do **not** jump ahead.  Each stage’s checkpoint is the foundation for the next.
 
+### One-command sanity check (`docker_debug.py`)
+
+While you move through the phases it’s handy to run the **interactive checker** to make sure nothing broke:
+
+```bash
+python environments/docker_debug.py my-environment:latest
+```
+
+The script walks the *same* checklist and prints coloured, human-friendly hints whenever something fails.
+
+| What it validates | Phase |
+|-------------------|-------|
+| Container starts & logs to **stderr** | 1 |
+| MCP server responds to an `initialize` request | 2 |
+| Discovers `setup`, `evaluate`, and interaction tools | 3 |
+| Calls `setup` / `evaluate`, checks telemetry & startup time | 4 |
+| Spawns three concurrent clients to stress-test resources | 5 |
+
+💡 **Run it after finishing each phase.** If the checker exits with a red ❌, scroll up for the gold-coloured *hint* block – it usually points directly to the root cause.
+
 ---
 
 ## Phase 1 – Write a *Simple* Dockerfile
@@ -32,7 +52,8 @@ Why stderr?  In Phase 2 the MCP server will reserve **stdout** for JSON-RPC traf
 ```dockerfile
 FROM python:3.11-slim
 
-WORKDIR /app
+WORKDIR /apphello
+
 COPY . .
 
 # Optional: install requirements
@@ -58,6 +79,8 @@ docker run --rm -it my-environment     # look for the log line on stderr
 
 Checkpoint reached?  Congratulations – move on.
 
+👉 Quick sanity check: `python environments/docker_debug.py my-environment:latest` (verifies Phase 1 automatically)
+
 Need inspiration?  Skim the real Dockerfiles used in the example browser environments:
 • [`simple_browser/Dockerfile`](./simple_browser/Dockerfile)
 • [`remote_browser/Dockerfile`](./remote_browser/Dockerfile)
@@ -129,6 +152,7 @@ CMD ["uv", "pip", "run", "python", "-m", "your_module_name"]  # Replace 'your_mo
 | 1 | **Direct stdio test** – pipe the JSON below into your script | Proves the Python code handles `initialize` without any client or Docker noise |
 | 2 | **MCP Inspector** – `npx @modelcontextprotocol/inspector python -m my_package.server` | Lets you click around: view capabilities, tools, resources |
 | 3 | **Inside Docker** – rebuild the image and run it | This is *exactly* how HUD will execute the server |
+| 4 | **Run `docker_debug.py`** – `python environments/docker_debug.py my-environment:latest` | Combines the above checks & points out common mistakes |
 
 #### JSON for step 1
 
@@ -154,6 +178,8 @@ If all three validations succeed, you have a real MCP server – time to make it
 
 **Goal →** tools are discoverable in the Inspector *and* callable from the HUD SDK.
 
+👉 After wiring in the tools, confirm with `python environments/docker_debug.py my-environment:latest` – it now checks for their presence and basic execution.
+
 1. Write **`setup`** and **`evaluate`** tools first – they are *lifecycle* tools and never shown to the LLM.
 2. Register at least one **interaction** tool (`computer`, `playwright`, or your own).
 

{hud_python-0.3.1 → hud_python-0.3.2}/environments/docker_debug.py

@@ -400,7 +400,7 @@ async def debug_mcp_docker(image: str) -> None:
         cmd = ["docker"] + mcp_config["test"]["args"]
         log_command(cmd)
 
-        log_info("Creating MCP client with auto-initialization...")
+        log_info("Creating MCP client via hud...")
         client = MCPClient(mcp_config=mcp_config, verbose=False)
 
         await client.initialize()
@@ -473,7 +473,8 @@ async def debug_mcp_docker(image: str) -> None:
             show_progress_bar(phases_completed, total_phases)
             return
 
-        await client.close()
+        # Keep client open for Phase 4
+        # await client.close()
 
     except Exception as e:
         log_error(f"Tool discovery failed: {e}")
@@ -503,14 +504,21 @@ async def debug_mcp_docker(image: str) -> None:
         setup_success = False
         if "setup" in [t.name for t in tools]:
             try:
-                log_info("Calling setup tool with test configuration...")
-                setup_result = await client.call_tool("setup", {"config": {}})
+                log_info("Calling setup tool (no params to test existence)...")
+                setup_result = await client.call_tool("setup", {})
 
-                if isinstance(setup_result, dict) and "status" in setup_result:
+                # Even if it errors, if we get a response it means the tool exists
+                if hasattr(setup_result, "isError") and setup_result.isError:
+                    log_info(
+                        f"Setup tool exists but returned error (expected): {setup_result.content[0].text if setup_result.content else 'Unknown error'}"
+                    )
+                    setup_success = True  # Tool exists, that's what we're checking
+                elif isinstance(setup_result, dict) and "status" in setup_result:
                     log_success(f"Setup tool returned: {setup_result}")
                     setup_success = setup_result.get("status") == "success"
                 else:
-                    log_error(f"Setup tool returned unexpected format: {setup_result}")
+                    log_success(f"Setup tool exists and returned: {type(setup_result)}")
+                    setup_success = True
             except Exception as e:
                 log_error(f"Setup tool failed: {e}")
 
@@ -518,10 +526,16 @@ async def debug_mcp_docker(image: str) -> None:
         evaluate_success = False
         if "evaluate" in [t.name for t in tools]:
             try:
-                log_info("Calling evaluate tool...")
-                eval_result = await client.call_tool("evaluate", {"config": {}})
+                log_info("Calling evaluate tool (no params to test existence)...")
+                eval_result = await client.call_tool("evaluate", {})
 
-                if (
+                # Even if it errors, if we get a response it means the tool exists
+                if hasattr(eval_result, "isError") and eval_result.isError:
+                    log_info(
+                        f"Evaluate tool exists but returned error (expected): {eval_result.content[0].text if eval_result.content else 'Unknown error'}"
+                    )
+                    evaluate_success = True  # Tool exists, that's what we're checking
+                elif (
                     isinstance(eval_result, dict)
                     and "reward" in eval_result
                     and "done" in eval_result
@@ -531,7 +545,8 @@ async def debug_mcp_docker(image: str) -> None:
                     )
                     evaluate_success = True
                 else:
-                    log_error(f"Evaluate tool returned unexpected format: {eval_result}")
+                    log_success(f"Evaluate tool exists and returned: {type(eval_result)}")
+                    evaluate_success = True
             except Exception as e:
                 log_error(f"Evaluate tool failed: {e}")
 
@@ -540,16 +555,20 @@ async def debug_mcp_docker(image: str) -> None:
         resources_found = []
         try:
             session = client._sessions.get("test")
-            if session:
-                resources = await session.list_resources()
-                for res in resources:
+            if session and hasattr(session, "connector"):
+                resources = await session.connector.list_resources()
+                for res in resources.resources:
                     resources_found.append(res.uri)
                     if "telemetry://live" in res.uri:
                         log_info(f"Found telemetry resource: {res.uri}")
                     elif "registry" in res.uri:
                         log_info(f"Found registry resource: {res.uri}")
+                if not resources_found:
+                    log_info("No resources exposed by this environment")
+            else:
+                log_info("Session connector not available for resource listing")
         except Exception as e:
-            log_error(f"Resource check failed: {e}")
+            log_info(f"Resource check skipped: {e}")
 
         # Performance check
         log_info("Checking initialization performance...")
@@ -569,11 +588,19 @@ async def debug_mcp_docker(image: str) -> None:
             log_success("Remote deployment readiness checks passed")
         else:
             log_error("Missing or failing lifecycle tools")
+            await client.close()
             show_progress_bar(phases_completed, total_phases)
             return
 
+        # Close client from Phase 3/4
+        await client.close()
+
     except Exception as e:
         log_error(f"Phase 4 failed: {e}")
+        try:
+            await client.close()
+        except:
+            pass
         show_progress_bar(phases_completed, total_phases)
         return
 
@@ -583,7 +610,6 @@ async def debug_mcp_docker(image: str) -> None:
     concurrent_clients = []
     try:
         import psutil
-        import asyncio
 
         # Get baseline resource usage
         process = psutil.Process()
@@ -635,15 +661,24 @@ async def debug_mcp_docker(image: str) -> None:
         # Test clean shutdown
         log_info("Testing clean shutdown of all clients...")
         for i, client in enumerate(concurrent_clients):
-            await client.close()
-            log_info(f"Client {i + 1} disconnected")
+            try:
+                await client.close()
+                log_info(f"Client {i + 1} disconnected")
+            except Exception as e:
+                log_info(f"Client {i + 1} close error: {e}")
 
-        # Verify cleanup
-        await asyncio.sleep(1)
-        final_memory = process.memory_info().rss / 1024 / 1024
-        memory_freed = current_memory - final_memory
+        # Small delay to allow cleanup
+        try:
+            await asyncio.sleep(0.5)
+        except asyncio.CancelledError:
+            pass
 
-        log_info(f"After cleanup: Memory={final_memory:.1f}MB (freed {memory_freed:.1f}MB)")
+        try:
+            final_memory = process.memory_info().rss / 1024 / 1024
+            memory_freed = current_memory - final_memory
+            log_info(f"After cleanup: Memory={final_memory:.1f}MB (freed {memory_freed:.1f}MB)")
+        except:
+            pass
 
         phases_completed = 5
         log_success("Concurrent client testing completed")
@@ -681,9 +716,16 @@ async def debug_mcp_docker(image: str) -> None:
 
     finally:
         # Ensure all clients are closed
-        for client in concurrent_clients:
+        if concurrent_clients:
+            log_info("Final cleanup of any remaining clients...")
+            for client in concurrent_clients:
+                try:
+                    await client.close()
+                except:
+                    pass
+            # Small delay for cleanup
             try:
-                await client.close()
+                await asyncio.sleep(0.2)
             except:
                 pass
 

{hud_python-0.3.1 → hud_python-0.3.2}/environments/simple_browser/README.md

@@ -44,7 +44,7 @@ import hud
 from mcp_use import MCPClient
 from hud.mcp import ClaudeMCPAgent
 
-BASE_URL = "https://orchestrator-v3.up.railway.app"
+BASE_URL = "https://mcp.hud.so"
 HUD_API_KEY = os.getenv("HUD_API_KEY")
 
 async def main():

{hud_python-0.3.1 → hud_python-0.3.2}/hud/task.py

@@ -62,6 +62,7 @@ class Task(BaseModel):
     # Description of the task, for extra information about its purpose and context
     description: str | None = None
 
+    # Gold file url for the task
     gold_file_url: str | None = None
 
     @classmethod

{hud_python-0.3.1 → hud_python-0.3.2}/hud/tools/computer/hud.py

@@ -31,6 +31,7 @@ class HudComputerTool:
         height: int | None = None,
         display_num: int | None = None,
         platform_type: Literal["auto", "xdo", "pyautogui"] = "auto",
+        executor: BaseExecutor | None = None,
         rescale_images: bool = False,
     ) -> None:
         """
@@ -44,6 +45,7 @@ class HudComputerTool:
                 - "auto": Automatically detect based on platform
                 - "xdo": Use XDOExecutor (Linux/X11 only)
                 - "pyautogui": Use PyAutoGUIExecutor (cross-platform)
+            executor: The executor to use. If None, will be auto-detected based on platform_type.
             rescale_images: If True, rescale screenshots. If False, only rescale action coordinates
         """
         # Use provided dimensions or defaults
@@ -70,6 +72,17 @@ class HudComputerTool:
         # Check if we need to scale
         self.needs_scaling = self.scale != 1.0
 
+        if executor is None:
+            self._choose_executor(platform_type, display_num)
+        else:
+            self.executor = executor
+
+    def _choose_executor(
+        self,
+        platform_type: Literal["auto", "xdo", "pyautogui"],
+        display_num: int | None,
+    ) -> None:
+        """Choose executor based on platform_type."""
         # Choose executor based on platform_type
         if platform_type == "auto":
             # Auto-detect based on platform

{hud_python-0.3.1 → hud_python-0.3.2}/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.3.1"
+    assert hud.__version__ == "0.3.2"

{hud_python-0.3.1 → hud_python-0.3.2}/hud/version.py

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

{hud_python-0.3.1 → hud_python-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hud-python"
-version = "0.3.1"
+version = "0.3.2"
 description = "SDK for the HUD platform."
 readme = "README.md"
 requires-python = ">=3.11, <3.14"