hud-python 0.4.18__py3-none-any.whl → 0.4.19__py3-none-any.whl

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/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/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.19"

hud/version.py

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

{hud_python-0.4.18.dist-info → hud_python-0.4.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hud-python
-Version: 0.4.18
+Version: 0.4.19
 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.dist-info → hud_python-0.4.19.dist-info}/RECORD

@@ -2,13 +2,13 @@ hud/__init__.py,sha256=BjAhZtsHbGN371Q8t3o4v4jltedkmDE85xW0yOILU9g,397
 hud/__main__.py,sha256=YR8Dq8OhINOsVfQ55PmRXXg4fEK84Rt_-rMtJ5rvhWo,145
 hud/settings.py,sha256=q9aZiHjvbL4oLE-N8AttTW4rmzS8zPMnsca-iMGyEGc,2362
 hud/types.py,sha256=gNnyS1G7aYHIR5sT3k3bOfSTFnPylUO6lNGLWbjbeYk,5149
-hud/version.py,sha256=8Ag1N-qzwxUt5QwVLTJ5Z43L6M6O6FLpCKva6zONOfc,105
+hud/version.py,sha256=TspylpJFduiccfFe6aqVOAungquP27FSDJSivDPvJ5E,105
 hud/agents/__init__.py,sha256=UoIkljWdbq4bM0LD-mSaw6w826EqdEjOk7r6glNYwYQ,286
-hud/agents/base.py,sha256=rbwYP_a6XTwhY_5CaBlE7SWflnTq1EOuDiNY2XeUWdM,28275
+hud/agents/base.py,sha256=t3bPRTKzGuejhSeo1jLNprlUv6zNU9ezQfP16tX_pXw,29562
 hud/agents/claude.py,sha256=_eD_XKZhVJ6grkHQfbS6JskztueomQcmJeGJMbfNdmE,14534
 hud/agents/langchain.py,sha256=1EgCy8jfjunsWxlPC5XfvfLS6_XZVrIF1ZjtHcrvhYw,9584
 hud/agents/openai.py,sha256=tvFYsZ5yaoLkfjMnHe-COxRttMsLRXBLPdSqgeipQRk,14257
-hud/agents/openai_chat_generic.py,sha256=Q6eKlKQIF2o04eGpIcBAyqpdcgRvuolbxmgWTT6ktEQ,10478
+hud/agents/openai_chat_generic.py,sha256=PQAD4GGE6sHs8R95qpgDBHEbSOJ7WXCYGYFmd3Nic1g,10628
 hud/agents/misc/__init__.py,sha256=BYi4Ytp9b_vycpZFXnr5Oyw6ncKLNNGml8Jrb7bWUb4,136
 hud/agents/misc/response_agent.py,sha256=pnaomb4H-QJm1YKU3tC1YnZXxOlDbTHIXaIH-6Nkb6I,3102
 hud/agents/tests/__init__.py,sha256=W-O-_4i34d9TTyEHV-O_q1Ai1gLhzwDaaPo02_TWQIY,34
@@ -157,10 +157,10 @@ hud/utils/tests/test_init.py,sha256=2QLQSGgyP9wJhOvPCusm_zjJad0qApOZi1BXpxcdHXQ,
 hud/utils/tests/test_mcp.py,sha256=0pUa16mL-bqbZDXp5NHBnt1gO5o10BOg7zTMHZ1DNPM,4023
 hud/utils/tests/test_progress.py,sha256=QSF7Kpi03Ff_l3mAeqW9qs1nhK50j9vBiSobZq7T4f4,7394
 hud/utils/tests/test_telemetry.py,sha256=5jl7bEx8C8b-FfFUko5pf4UY-mPOR-9HaeL98dGtVHM,2781
-hud/utils/tests/test_version.py,sha256=Ur5o4UVJbPy4rYJUIc3yBCTK-mk9CAf_7bHv2qSPJEI,160
+hud/utils/tests/test_version.py,sha256=bB6kVxiVIBfXJAEJpmnhn0ml3FG8Gk5ByfSd2fgoARc,160
 hud/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hud_python-0.4.18.dist-info/METADATA,sha256=vvUR4EBJmH6WqrLg2OxsupIJLs_6S8aVPaCRJjN3sJI,20287
-hud_python-0.4.18.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-hud_python-0.4.18.dist-info/entry_points.txt,sha256=jJbodNFg1m0-CDofe5AHvB4zKBq7sSdP97-ohaQ3ae4,63
-hud_python-0.4.18.dist-info/licenses/LICENSE,sha256=yIzBheVUf86FC1bztAcr7RYWWNxyd3B-UJQ3uddg1HA,1078
-hud_python-0.4.18.dist-info/RECORD,,
+hud_python-0.4.19.dist-info/METADATA,sha256=T-D9DILS-I5e6xdOmJOIU6wOPpXn3yY_zxk0bKFfPts,20287
+hud_python-0.4.19.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hud_python-0.4.19.dist-info/entry_points.txt,sha256=jJbodNFg1m0-CDofe5AHvB4zKBq7sSdP97-ohaQ3ae4,63
+hud_python-0.4.19.dist-info/licenses/LICENSE,sha256=yIzBheVUf86FC1bztAcr7RYWWNxyd3B-UJQ3uddg1HA,1078
+hud_python-0.4.19.dist-info/RECORD,,