hud-python 0.4.18__tar.gz → 0.4.20__tar.gz

{hud_python-0.4.18 → hud_python-0.4.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hud-python
-Version: 0.4.18
+Version: 0.4.20
 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.4.18 → hud_python-0.4.20}/examples/README.md

@@ -20,6 +20,19 @@ python examples/01_hello_2048.py
 
 > | Requires Docker and `ANTHROPIC_API_KEY` environment variable.
 
+### 03_browser_agent_loop.py
+Quick start for the browser environment (Claude). Supports multiple demo apps.
+
+```bash
+# 2048 (default)
+python examples/03_browser_agent_loop.py
+
+# Todo app
+python examples/03_browser_agent_loop.py --app todo
+```
+
+> | Requires Docker (exposes port 8080) and `ANTHROPIC_API_KEY`.
+
 ## Core Patterns
 
 ### 02_agent_lifecycle.py
@@ -50,35 +63,12 @@ Using the legacy `mcp_use` client for multi-server setups.
 ### integration_otel.py
 Custom OpenTelemetry backend integration (e.g., Jaeger).
 
-## Prerequisites
-
-| Requirement | Used For |
-|-------------|----------|
-| Docker | Running environment containers |
-| `HUD_API_KEY` | Cloud deployments and telemetry |
-| `ANTHROPIC_API_KEY` | Claude agent examples |
+### openai_compatible_agent.py
+OpenAI-compatible chat.completions agent with both text and browser 2048 environments.
 
-## Common Pattern
-
-All examples follow this structure:
-
-```python
-import asyncio, hud
-from hud.datasets import Task
-from hud.agents import ClaudeAgent
-
-async def main():
-    with hud.trace("example-name"):
-        task = Task(
-            prompt="Your task here",
-            mcp_config={...}
-        )
-        
-        agent = ClaudeAgent()
-        result = await agent.run(task)
-        print(f"Reward: {result.reward}")
-
-asyncio.run(main())
+```bash
+export OPENAI_API_KEY=your-key           # or dummy value for local servers
+# export OPENAI_BASE_URL=http://localhost:8000/v1  # e.g., vllm
+python examples/openai_compatible_agent.py --mode text     # text environment
+python examples/openai_compatible_agent.py --mode browser  # browser environment
 ```
-
-> | The agent automatically creates an MCP client from `task.mcp_config` if none is provided.

{hud_python-0.4.18 → hud_python-0.4.20}/hud/agents/base.py

@@ -30,9 +30,19 @@ class MCPAgent(ABC):
     """
     Base class for MCP-enabled agents.
 
-    This class provides the foundation for agents that interact with MCP servers,
-    handling tool discovery and filtering while leaving provider-specific
-    implementation details to subclasses.
+    Provides common behavior for agents that interact with MCP servers, including:
+    - Client management: accepts an `AgentMCPClient` or auto-creates one at
+      runtime when `run()` is called with a `Task` that includes `mcp_config`.
+    - Tool lifecycle: discovery, filtering (`allowed_tools`, `disallowed_tools`),
+      and automatic marking of lifecycle tools (setup/evaluate) from a `Task`.
+    - Messaging: system prompt handling, optional inclusion of setup output on
+      the first turn, and control over initial screenshots.
+    - Telemetry & UX: standardized logging/printing via `HUDDesign` and optional
+      automatic tracing (`auto_trace`).
+
+    Subclasses implement provider-specific formatting and response fetching
+    by overriding these abstract methods: `get_system_messages`, `get_response`,
+    `format_blocks`, and `format_tool_results`.
     """
 
     metadata: dict[str, Any]
@@ -59,14 +69,23 @@ class MCPAgent(ABC):
         Initialize the base MCP agent.
 
         Args:
-            mcp_client: AgentMCPClient instance for server connections
-            allowed_tools: List of tool names to allow (None = all tools)
-            disallowed_tools: List of tool names to disallow
-            lifecycle_tools: List of tool names to use for lifecycle tools
-            initial_screenshot: Whether to capture screenshot before first prompt
-            system_prompt: System prompt to use
-            append_setup_output: Whether to append setup tool output to initial messages
-            verbose: If True, sets logging level to INFO. If False, only WARNING and above.
+            mcp_client: Client for connecting to MCP servers. If None, a client
+                is auto-created at runtime when `run()` is called with a `Task`
+                that provides `mcp_config`.
+            allowed_tools: Names of tools to allow (None means allow all).
+            disallowed_tools: Names of tools to always exclude.
+            lifecycle_tools: Tools reserved for lifecycle phases (e.g., setup,
+                evaluate). These are hidden from normal tool calling.
+            system_prompt: System prompt to seed the conversation.
+            append_setup_output: Whether to append setup tool output to the
+                first turn's messages.
+            initial_screenshot: Whether to include an initial screenshot before
+                the first prompt (when supported by the environment).
+            model_name: Label used in telemetry/logging to identify the model.
+            response_agent: Optional automation that can respond to the model's
+                outputs to keep the loop going (e.g., auto-continue/stop).
+            auto_trace: If True, automatically creates a trace/span for runs.
+            verbose: If True, increases logging verbosity for developer UX.
         """
 
         self.mcp_client = mcp_client

{hud_python-0.4.18 → hud_python-0.4.20}/hud/agents/claude.py

@@ -306,35 +306,49 @@ class ClaudeAgent(MCPAgent):
         """Convert MCP tools to Claude tool format."""
         claude_tools = []
         self._claude_to_mcp_tool_map = {}  # Reset mapping
-
+        
+        # Find computer tool by priority
+        computer_tool_priority = ["anthropic_computer", "computer_anthropic", "computer"]
+        selected_computer_tool = None
+        
+        for priority_name in computer_tool_priority:
+            for tool in self._available_tools:
+                if tool.name == priority_name:
+                    selected_computer_tool = tool
+                    break
+            if selected_computer_tool:
+                break
+        
+        # Add the selected computer tool if found
+        if selected_computer_tool:
+            claude_tool = {
+                "type": "computer_20250124",
+                "name": "computer",
+                "display_width_px": self.metadata["display_width"],
+                "display_height_px": self.metadata["display_height"],
+            }
+            # Map Claude's "computer" back to the actual MCP tool name
+            self._claude_to_mcp_tool_map["computer"] = selected_computer_tool.name
+            claude_tools.append(claude_tool)
+            logger.debug(f"Using {selected_computer_tool.name} as computer tool for Claude")
+        
+        # Add other non-computer tools
         for tool in self._available_tools:
-            # Special handling for computer use tools
-            if tool.name in ["computer", "computer_anthropic", "anthropic_computer"]:
-                # Use Claude's native computer use format with configurable dimensions
-                claude_tool = {
-                    "type": "computer_20250124",
-                    "name": "computer",
-                    "display_width_px": self.metadata["display_width"],
-                    "display_height_px": self.metadata["display_height"],
-                }
-                # Map Claude's "computer" back to the actual MCP tool name
-                self._claude_to_mcp_tool_map["computer"] = tool.name
-            elif tool.name not in self.lifecycle_tools:
-                # Convert regular tools
-                claude_tool = {
-                    "name": tool.name,
-                    "description": tool.description or f"Execute {tool.name}",
-                    "input_schema": tool.inputSchema
-                    or {
-                        "type": "object",
-                        "properties": {},
-                    },
-                }
-                # Direct mapping for non-computer tools
-                self._claude_to_mcp_tool_map[tool.name] = tool.name
-            else:
+            # Skip computer tools (already handled) and lifecycle tools
+            if tool.name in computer_tool_priority or tool.name in self.lifecycle_tools:
                 continue
-
+                
+            claude_tool = {
+                "name": tool.name,
+                "description": tool.description or f"Execute {tool.name}",
+                "input_schema": tool.inputSchema
+                or {
+                    "type": "object",
+                    "properties": {},
+                },
+            }
+            # Direct mapping for non-computer tools
+            self._claude_to_mcp_tool_map[tool.name] = tool.name
             claude_tools.append(claude_tool)
 
         self.claude_tools = claude_tools

{hud_python-0.4.18 → hud_python-0.4.20}/hud/agents/openai_chat_generic.py

@@ -7,7 +7,7 @@ through the existing :class:`hud.agent.MCPAgent` scaffolding.
 Key points:
 - Stateless, no special server-side conversation state is assumed.
 - Accepts an :class:`openai.AsyncOpenAI` client, caller can supply their own
-  base_url / api_key (e.g. ART, llama.cpp, together.ai, …)
+  base_url / api_key (e.g. llama.cpp, together.ai, …)
 - All HUD features (step_count, OTel spans, tool filtering, screenshots, …)
   come from the ``MCPAgent`` base class, we only implement the three abstract
   methods
@@ -30,8 +30,6 @@ if TYPE_CHECKING:
     from openai import AsyncOpenAI
     from openai.types.chat import ChatCompletionToolParam
 
-    from hud.clients import AgentMCPClient
-
 logger = logging.getLogger(__name__)
 
 
@@ -40,19 +38,19 @@ class GenericOpenAIChatAgent(MCPAgent):
 
     def __init__(
         self,
-        mcp_client: AgentMCPClient,
         *,
         openai_client: AsyncOpenAI,
         model_name: str = "gpt-4o-mini",
         parallel_tool_calls: bool = False,
-        logprobs: bool = False,
+        completion_kwargs: dict[str, Any] | None = None,
         **agent_kwargs: Any,
     ) -> None:
-        super().__init__(mcp_client=mcp_client, **agent_kwargs)
+        # Accept base-agent settings via **agent_kwargs (e.g., mcp_client, system_prompt, etc.)
+        super().__init__(**agent_kwargs)
         self.oai = openai_client
         self.model_name = model_name
         self.parallel_tool_calls = parallel_tool_calls
-        self.logprobs = logprobs
+        self.completion_kwargs: dict[str, Any] = completion_kwargs or {}
         self.conversation_history = []
 
     @staticmethod
@@ -177,12 +175,15 @@ class GenericOpenAIChatAgent(MCPAgent):
         # Convert MCP tool schemas to OpenAI format
         mcp_schemas = self.get_tool_schemas()
 
+        protected_keys = {"model", "messages", "tools", "parallel_tool_calls"}
+        extra = {k: v for k, v in (self.completion_kwargs or {}).items() if k not in protected_keys}
+
         response = await self.oai.chat.completions.create(
             model=self.model_name,
             messages=messages,
             tools=cast("list[ChatCompletionToolParam]", mcp_schemas),
             parallel_tool_calls=self.parallel_tool_calls,
-            logprobs=self.logprobs,
+            **extra,
         )
 
         choice = response.choices[0]
@@ -247,9 +248,7 @@ class GenericOpenAIChatAgent(MCPAgent):
                         image_parts.append(
                             {
                                 "type": "image_url",
-                                "image_url": {
-                                    "url": f"data:{mime_type};base64,{data}"
-                                },
+                                "image_url": {"url": f"data:{mime_type};base64,{data}"},
                             }
                         )
                 elif isinstance(item, types.TextContent):
@@ -276,7 +275,7 @@ class GenericOpenAIChatAgent(MCPAgent):
                 # Add a user message with the images
                 content_with_images = [
                     {"type": "text", "text": "Tool returned the following:"},
-                    *image_parts
+                    *image_parts,
                 ]
                 rendered.append(
                     {

{hud_python-0.4.18 → hud_python-0.4.20}/hud/clients/base.py

@@ -130,31 +130,19 @@ class BaseHUDClient(AgentMCPClient):
         logger.debug("Initializing MCP client...")
 
         try:
+            # Check if API key is set for HUD API
+            for server_config in self._mcp_config.values():
+                url = server_config.get("url", "")
+                headers = server_config.get("headers", {})
+                if "mcp.hud.so" in url and len(headers.get("Authorization", "")) < 10:
+                    raise RuntimeError(
+                        "Please ensure your HUD_API_KEY environment variable is set correctly."
+                        "You can get an API key at https://app.hud.so"
+                    )
             # Subclasses implement connection
             await self._connect(self._mcp_config)
-        except RuntimeError as e:
-            # Re-raise authentication errors with clear message
-            if "Authentication failed" in str(e):
-                raise
-            raise
         except Exception as e:
-            # Check for authentication errors in the exception chain
-            error_msg = str(e)
-            if "401" in error_msg or "Unauthorized" in error_msg:
-                # Check if connecting to HUD API
-                for server_config in self._mcp_config.values():
-                    url = server_config.get("url", "")
-                    if "mcp.hud.so" in url:
-                        raise RuntimeError(
-                            "Authentication failed for HUD API. "
-                            "Please ensure your HUD_API_KEY environment variable is set correctly. "
-                            "You can get an API key at https://app.hud.so"
-                        ) from e
-                raise RuntimeError(
-                    "Authentication failed (401 Unauthorized). "
-                    "Please check your credentials or API key."
-                ) from e
-            raise
+            raise e
 
         # Common hud behavior - fetch telemetry
         await self._fetch_telemetry()

{hud_python-0.4.18 → hud_python-0.4.20}/hud/datasets/task.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import logging
 from collections import defaultdict
 from string import Template
 from typing import Any
@@ -12,6 +13,8 @@ from pydantic import BaseModel, Field, field_validator
 from hud.settings import settings
 from hud.types import MCPToolCall
 
+logger = logging.getLogger(__name__)
+
 
 class Task(BaseModel):
     """
@@ -90,6 +93,8 @@ 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")
 
         def substitute_in_value(obj: Any) -> Any:
             """Recursively substitute variables in nested structures."""

{hud_python-0.4.18 → hud_python-0.4.20}/hud/tools/playwright.py

@@ -153,7 +153,7 @@ class PlaywrightTool(BaseTool):
         """Ensure browser is launched and ready."""
         if self._browser is None or not self._browser.is_connected():
             if self._cdp_url:
-                logger.info("Connecting to remote browser via CDP: %s", self._cdp_url)
+                logger.info("Connecting to remote browser via CDP")
             else:
                 logger.info("Launching Playwright browser...")
 

{hud_python-0.4.18 → hud_python-0.4.20}/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.4.18"
+    assert hud.__version__ == "0.4.20"

{hud_python-0.4.18 → hud_python-0.4.20}/hud/version.py

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

{hud_python-0.4.18 → hud_python-0.4.20}/pyproject.toml

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