hud-python 0.5.1__py3-none-any.whl → 0.5.13__py3-none-any.whl

hud/agents/operator.py

@@ -17,14 +17,14 @@ from openai.types.responses.response_input_param import (
     FunctionCallOutput,
 )
 from openai.types.shared_params.reasoning import Reasoning
-from pydantic import ConfigDict
 
 from hud.tools.computer.settings import computer_settings
 from hud.types import BaseAgentConfig, MCPToolCall, MCPToolResult
 from hud.utils.types import with_signature
 
-from .base import BaseCreateParams, MCPAgent
-from .openai import OpenAIAgent, OpenAIConfig
+from .base import MCPAgent
+from .openai import OpenAIAgent
+from .types import OperatorConfig, OperatorCreateParams
 
 if TYPE_CHECKING:
     from openai.types.responses.response_computer_tool_call import PendingSafetyCheck
@@ -50,20 +50,6 @@ what they asked.
 """.strip()
 
 
-class OperatorConfig(OpenAIConfig):
-    """Configuration model for `OperatorAgent`."""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    model_name: str = "Operator"
-    model: str = "computer-use-preview"
-    environment: Literal["windows", "mac", "linux", "ubuntu", "browser"] = "linux"
-
-
-class OperatorCreateParams(BaseCreateParams, OperatorConfig):
-    pass
-
-
 class OperatorAgent(OpenAIAgent):
     """
     Backwards-compatible Operator agent built on top of OpenAIAgent.
@@ -129,6 +115,8 @@ class OperatorAgent(OpenAIAgent):
                 display_height=self._operator_display_height,
                 environment=self._operator_environment,
             )
+        if tool.name == "computer" or tool.name.endswith("_computer"):
+            return None
         return super()._to_openai_tool(tool)
 
     def _extract_tool_call(self, item: Any) -> MCPToolCall | None:

hud/agents/resolver.py

@@ -0,0 +1,70 @@
+"""Model resolution - maps model strings to agent classes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from hud.agents.base import MCPAgent
+
+__all__ = ["resolve_cls"]
+
+_models_cache: list[dict[str, Any]] | None = None
+
+# Provider name → AgentType value (only anthropic differs)
+_PROVIDER_TO_AGENT = {"anthropic": "claude"}
+
+
+def _fetch_gateway_models() -> list[dict[str, Any]]:
+    """Fetch available models from HUD gateway (cached)."""
+    global _models_cache
+    if _models_cache is not None:
+        return _models_cache
+
+    import httpx
+
+    from hud.settings import settings
+
+    if not settings.api_key:
+        return []
+
+    try:
+        resp = httpx.get(
+            f"{settings.hud_gateway_url}/models",
+            headers={"Authorization": f"Bearer {settings.api_key}"},
+            timeout=10.0,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        _models_cache = data.get("data", data) if isinstance(data, dict) else data
+        return _models_cache or []
+    except Exception:
+        return []
+
+
+def resolve_cls(model: str) -> tuple[type[MCPAgent], dict[str, Any] | None]:
+    """Resolve model string to (agent_class, gateway_info).
+
+    Returns:
+        (agent_class, None) for known AgentTypes
+        (agent_class, gateway_model_info) for gateway models
+    """
+    from hud.types import AgentType
+
+    # Known AgentType → no gateway info
+    try:
+        return AgentType(model).cls, None
+    except ValueError:
+        pass
+
+    # Gateway lookup
+    for m in _fetch_gateway_models():
+        if model in (m.get("id"), m.get("name"), m.get("model")):
+            provider = (m.get("provider") or "openai_compatible").lower()
+            agent_str = _PROVIDER_TO_AGENT.get(provider, provider)
+            try:
+                return AgentType(agent_str).cls, m
+            except ValueError:
+                return AgentType.OPENAI_COMPATIBLE.cls, m
+
+    raise ValueError(f"Model '{model}' not found")

hud/agents/tests/test_claude.py

@@ -22,7 +22,7 @@ from hud.types import MCPToolCall, MCPToolResult
 if TYPE_CHECKING:
     from collections.abc import Generator
 
-    from anthropic.types.beta import BetaImageBlockParam, BetaMessageParam, BetaTextBlockParam
+    from anthropic.types.beta import BetaMessageParam
 
 
 class MockEvalContext(EvalContext):
@@ -123,9 +123,7 @@ class TestClaudeHelperFunctions:
     def test_tool_use_content_block(self) -> None:
         """Test tool result content block creation."""
         tool_use_id = "tool_123"
-        content: list[BetaTextBlockParam | BetaImageBlockParam] = [
-            text_to_content_block("Result text")
-        ]
+        content = [text_to_content_block("Result text")]
 
         result = tool_use_content_block(tool_use_id, content)
 

hud/agents/tests/test_openai.py

@@ -128,8 +128,9 @@ class TestOpenAIAgent:
     async def test_init_without_client_no_api_key(self) -> None:
         """Test agent initialization fails without API key."""
         with patch("hud.agents.openai.settings") as mock_settings:
+            mock_settings.api_key = None
             mock_settings.openai_api_key = None
-            with pytest.raises(ValueError, match="OpenAI API key not found"):
+            with pytest.raises(ValueError, match="No API key found"):
                 OpenAIAgent.create()
 
     @pytest.mark.asyncio

hud/agents/tests/test_resolver.py

@@ -0,0 +1,192 @@
+"""Tests for model resolution and create_agent."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hud.agents import create_agent
+from hud.agents.resolver import resolve_cls
+
+
+class TestResolveCls:
+    """Tests for resolve_cls function."""
+
+    def test_resolves_known_agent_type(self) -> None:
+        """Known AgentType strings resolve to their class."""
+        from hud.agents.claude import ClaudeAgent
+
+        cls, gateway_info = resolve_cls("claude")
+        assert cls == ClaudeAgent
+        assert gateway_info is None
+
+    def test_resolves_openai(self) -> None:
+        """Resolves 'openai' to OpenAIAgent."""
+        from hud.agents import OpenAIAgent
+
+        cls, _gateway_info = resolve_cls("openai")
+        assert cls == OpenAIAgent
+
+    def test_resolves_gemini(self) -> None:
+        """Resolves 'gemini' to GeminiAgent."""
+        from hud.agents.gemini import GeminiAgent
+
+        cls, _gateway_info = resolve_cls("gemini")
+        assert cls == GeminiAgent
+
+    def test_unknown_model_without_gateway_raises(self) -> None:
+        """Unknown model with no gateway models raises ValueError."""
+        with (
+            patch("hud.agents.resolver._fetch_gateway_models", return_value=[]),
+            pytest.raises(ValueError, match="not found"),
+        ):
+            resolve_cls("unknown-model-xyz")
+
+    def test_resolves_gateway_model(self) -> None:
+        """Resolves model found in gateway."""
+        from hud.agents import OpenAIAgent
+
+        mock_models = [
+            {"id": "gpt-4o", "model": "gpt-4o", "provider": "openai"},
+        ]
+
+        with patch("hud.agents.resolver._fetch_gateway_models", return_value=mock_models):
+            cls, info = resolve_cls("gpt-4o")
+            assert cls == OpenAIAgent
+            assert info is not None
+            assert info["id"] == "gpt-4o"
+
+    def test_resolves_anthropic_provider_to_claude(self) -> None:
+        """Provider 'anthropic' maps to ClaudeAgent."""
+        from hud.agents.claude import ClaudeAgent
+
+        mock_models = [
+            {"id": "claude-sonnet", "model": "claude-3-sonnet", "provider": "anthropic"},
+        ]
+
+        with patch("hud.agents.resolver._fetch_gateway_models", return_value=mock_models):
+            cls, _info = resolve_cls("claude-sonnet")
+            assert cls == ClaudeAgent
+
+    def test_resolves_unknown_provider_to_openai_compatible(self) -> None:
+        """Unknown provider maps to OpenAIChatAgent."""
+        from hud.agents.openai_chat import OpenAIChatAgent
+
+        mock_models = [
+            {"id": "custom-model", "model": "custom", "provider": "custom-provider"},
+        ]
+
+        with patch("hud.agents.resolver._fetch_gateway_models", return_value=mock_models):
+            cls, _info = resolve_cls("custom-model")
+            assert cls == OpenAIChatAgent
+
+
+class TestCreateAgent:
+    """Tests for create_agent function - gateway-only."""
+
+    def test_creates_with_gateway_client(self) -> None:
+        """create_agent always uses gateway routing."""
+        from hud.agents import OpenAIAgent
+
+        mock_models = [
+            {"id": "gpt-4o", "model": "gpt-4o", "provider": "openai"},
+        ]
+
+        with (
+            patch("hud.agents.resolver._fetch_gateway_models", return_value=mock_models),
+            patch.object(OpenAIAgent, "create") as mock_create,
+            patch("hud.agents.gateway.build_gateway_client") as mock_build_client,
+        ):
+            mock_client = MagicMock()
+            mock_build_client.return_value = mock_client
+            mock_agent = MagicMock()
+            mock_create.return_value = mock_agent
+
+            agent = create_agent("gpt-4o")
+
+            # Should have set model and model_client
+            call_kwargs = mock_create.call_args.kwargs
+            assert call_kwargs["model"] == "gpt-4o"
+            assert "model_client" in call_kwargs
+            assert agent == mock_agent
+
+    def test_passes_kwargs_to_create(self) -> None:
+        """Extra kwargs are passed to agent.create()."""
+        from hud.agents import OpenAIAgent
+
+        mock_models = [
+            {"id": "gpt-4o", "model": "gpt-4o", "provider": "openai"},
+        ]
+
+        with (
+            patch("hud.agents.resolver._fetch_gateway_models", return_value=mock_models),
+            patch.object(OpenAIAgent, "create") as mock_create,
+            patch("hud.agents.gateway.build_gateway_client"),
+        ):
+            mock_create.return_value = MagicMock()
+
+            create_agent("gpt-4o", temperature=0.5, max_tokens=1000)
+
+            call_kwargs = mock_create.call_args.kwargs
+            assert call_kwargs["temperature"] == 0.5
+            assert call_kwargs["max_tokens"] == 1000
+
+    def test_known_agent_type_also_uses_gateway(self) -> None:
+        """Even 'claude' string uses gateway (it's a gateway shortcut)."""
+        from hud.agents.claude import ClaudeAgent
+
+        with (
+            patch.object(ClaudeAgent, "create") as mock_create,
+            patch("hud.agents.gateway.build_gateway_client") as mock_build_client,
+        ):
+            mock_client = MagicMock()
+            mock_build_client.return_value = mock_client
+            mock_create.return_value = MagicMock()
+
+            create_agent("claude")
+
+            # Should still build gateway client
+            mock_build_client.assert_called_once()
+            call_kwargs = mock_create.call_args.kwargs
+            assert "model_client" in call_kwargs
+
+
+class TestBuildGatewayClient:
+    """Tests for build_gateway_client function."""
+
+    def test_builds_anthropic_client(self) -> None:
+        """Builds AsyncAnthropic for anthropic provider."""
+        from hud.agents.gateway import build_gateway_client
+
+        with patch("hud.settings.settings") as mock_settings:
+            mock_settings.api_key = "test-key"
+            mock_settings.hud_gateway_url = "https://gateway.hud.ai"
+
+            with patch("anthropic.AsyncAnthropic") as mock_client_cls:
+                build_gateway_client("anthropic")
+                mock_client_cls.assert_called_once()
+
+    def test_builds_openai_client_for_openai(self) -> None:
+        """Builds AsyncOpenAI for openai provider."""
+        from hud.agents.gateway import build_gateway_client
+
+        with patch("hud.settings.settings") as mock_settings:
+            mock_settings.api_key = "test-key"
+            mock_settings.hud_gateway_url = "https://gateway.hud.ai"
+
+            with patch("openai.AsyncOpenAI") as mock_client_cls:
+                build_gateway_client("openai")
+                mock_client_cls.assert_called_once()
+
+    def test_builds_openai_client_for_unknown(self) -> None:
+        """Builds AsyncOpenAI for unknown providers (openai-compatible)."""
+        from hud.agents.gateway import build_gateway_client
+
+        with patch("hud.settings.settings") as mock_settings:
+            mock_settings.api_key = "test-key"
+            mock_settings.hud_gateway_url = "https://gateway.hud.ai"
+
+            with patch("openai.AsyncOpenAI") as mock_client_cls:
+                build_gateway_client("together")
+                mock_client_cls.assert_called_once()

hud/agents/types.py

@@ -0,0 +1,148 @@
+"""Agent configuration types.
+
+Config classes are defined here separately from agent implementations
+to allow importing them without requiring SDK dependencies (anthropic, google-genai).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+from hud.types import BaseAgentConfig
+
+# Alias to accept both 'model' and 'checkpoint_name' (backwards compat)
+_model_alias = AliasChoices("model", "checkpoint_name")
+
+
+class BaseCreateParams(BaseModel):
+    """Runtime parameters for agent creation."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    ctx: Any = None  # EvalContext or Environment
+    auto_respond: bool = False
+    verbose: bool = False
+
+
+# -----------------------------------------------------------------------------
+# Claude
+# -----------------------------------------------------------------------------
+
+
+class ClaudeConfig(BaseAgentConfig):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    model_name: str = "Claude"
+    model: str = Field(default="claude-sonnet-4-5", validation_alias=_model_alias)
+    model_client: Any = None  # AsyncAnthropic | AsyncAnthropicBedrock
+    max_tokens: int = 16384
+    use_computer_beta: bool = True
+    validate_api_key: bool = True
+
+
+class ClaudeCreateParams(BaseCreateParams, ClaudeConfig):
+    pass
+
+
+# -----------------------------------------------------------------------------
+# Gemini
+# -----------------------------------------------------------------------------
+
+
+class GeminiConfig(BaseAgentConfig):
+    """Configuration for GeminiAgent."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    model_name: str = "Gemini"
+    model: str = Field(default="gemini-3-pro-preview", validation_alias=_model_alias)
+    model_client: Any = None  # genai.Client
+    temperature: float = 1.0
+    top_p: float = 0.95
+    top_k: int = 40
+    max_output_tokens: int = 8192
+    validate_api_key: bool = True
+
+
+class GeminiCreateParams(BaseCreateParams, GeminiConfig):
+    pass
+
+
+class GeminiCUAConfig(GeminiConfig):
+    """Configuration for GeminiCUAAgent."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    model_name: str = "GeminiCUA"
+    model: str = Field(
+        default="gemini-2.5-computer-use-preview-10-2025", validation_alias=_model_alias
+    )
+    excluded_predefined_functions: list[str] = Field(default_factory=list)
+
+
+class GeminiCUACreateParams(BaseCreateParams, GeminiCUAConfig):
+    pass
+
+
+# -----------------------------------------------------------------------------
+# OpenAI
+# -----------------------------------------------------------------------------
+
+
+class OpenAIConfig(BaseAgentConfig):
+    """Configuration for OpenAIAgent."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    model_name: str = "OpenAI"
+    model: str = Field(default="gpt-5.1", validation_alias=_model_alias)
+    model_client: Any = None  # AsyncOpenAI
+    max_output_tokens: int | None = None
+    temperature: float | None = None
+    reasoning: Any = None  # openai Reasoning
+    tool_choice: Any = None  # openai ToolChoice
+    truncation: Literal["auto", "disabled"] | None = None
+    parallel_tool_calls: bool | None = None
+    validate_api_key: bool = True
+
+
+class OpenAICreateParams(BaseCreateParams, OpenAIConfig):
+    pass
+
+
+class OpenAIChatConfig(BaseAgentConfig):
+    """Configuration for OpenAIChatAgent."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    model_name: str = "OpenAI Chat"
+    model: str = Field(default="gpt-5-mini", validation_alias=_model_alias)
+    openai_client: Any = None  # AsyncOpenAI
+    api_key: str | None = None
+    base_url: str | None = None
+    completion_kwargs: dict[str, Any] = Field(default_factory=dict)
+
+
+class OpenAIChatCreateParams(BaseCreateParams, OpenAIChatConfig):
+    pass
+
+
+# -----------------------------------------------------------------------------
+# Operator
+# -----------------------------------------------------------------------------
+
+
+class OperatorConfig(OpenAIConfig):
+    """Configuration for OperatorAgent."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    model_name: str = "Operator"
+    model: str = Field(default="computer-use-preview", validation_alias=_model_alias)
+    environment: Literal["windows", "mac", "linux", "ubuntu", "browser"] = "linux"
+
+
+class OperatorCreateParams(BaseCreateParams, OperatorConfig):
+    pass

hud/cli/__init__.py

@@ -741,6 +741,11 @@ def build(
     platform: str | None = typer.Option(
         None, "--platform", help="Set Docker target platform (e.g., linux/amd64)"
     ),
+    secrets: list[str] | None = typer.Option(  # noqa: B008
+        None,
+        "--secret",
+        help=("Docker build secret (repeatable), e.g. --secret id=GITHUB_TOKEN,env=GITHUB_TOKEN"),
+    ),
     remote_cache: str | None = typer.Option(
         None, "--remote-cache", help="Enable remote cache using Amazon ECR with specified repo name"
     ),
@@ -757,7 +762,8 @@ def build(
         hud build environments/text_2048 -e API_KEY=secret
         hud build . --tag my-env:v1.0 -e VAR1=value1 -e VAR2=value2
         hud build . --no-cache       # Force rebuild
-        hud build . --remote-cache my-cache-repo   # Use ECR remote cache (requires AWS_ACCOUNT_ID and AWS_DEFAULT_REGION)[/not dim]
+        hud build . --remote-cache my-cache-repo   # Use ECR remote cache (requires AWS_ACCOUNT_ID and AWS_DEFAULT_REGION)
+        hud build . --build-arg NODE_ENV=production  # Pass Docker build args[/not dim]
     """  # noqa: E501
     # Parse directory and extra arguments
     if params:
@@ -767,8 +773,9 @@ def build(
         directory = "."
         extra_args = []
 
-    # Parse environment variables from extra args
+    # Parse environment variables and build args from extra args
     env_vars = {}
+    build_args = {}
     i = 0
     while i < len(extra_args):
         if extra_args[i] == "-e" and i + 1 < len(extra_args):
@@ -792,10 +799,34 @@ def build(
                 key, value = env_arg.split("=", 1)
                 env_vars[key] = value
             i += 2
+        elif extra_args[i] == "--build-arg" and i + 1 < len(extra_args):
+            # Parse --build-arg KEY=VALUE format
+            build_arg = extra_args[i + 1]
+            if "=" in build_arg:
+                key, value = build_arg.split("=", 1)
+                build_args[key] = value
+            i += 2
+        elif extra_args[i].startswith("--build-arg="):
+            # Parse --build-arg=KEY=VALUE format
+            build_arg = extra_args[i][12:]  # Remove --build-arg=
+            if "=" in build_arg:
+                key, value = build_arg.split("=", 1)
+                build_args[key] = value
+            i += 1
         else:
             i += 1
 
-    build_command(directory, tag, no_cache, verbose, env_vars, platform, remote_cache)
+    build_command(
+        directory,
+        tag,
+        no_cache,
+        verbose,
+        env_vars,
+        platform,
+        secrets,
+        remote_cache,
+        build_args or None,
+    )
 
 
 @app.command()

hud/cli/build.py

@@ -555,11 +555,13 @@ def build_docker_image(
     verbose: bool = False,
     build_args: dict[str, str] | None = None,
     platform: str | None = None,
+    secrets: list[str] | None = None,
     remote_cache: str | None = None,
 ) -> bool:
     """Build a Docker image from a directory."""
     hud_console = HUDConsole()
     build_args = build_args or {}
+    secrets = secrets or []
 
     # Check if Dockerfile exists (prefer Dockerfile.hud)
     dockerfile = find_dockerfile(directory)
@@ -629,6 +631,10 @@ def build_docker_image(
     for key, value in build_args.items():
         cmd.extend(["--build-arg", f"{key}={value}"])
 
+    # Add secrets
+    for secret in secrets:
+        cmd.extend(["--secret", secret])
+
     cmd.append(str(directory))
 
     # Always show build output
@@ -636,7 +642,10 @@ def build_docker_image(
 
     try:
         # Use Docker's native output formatting - no capture, let Docker handle display
-        result = subprocess.run(cmd, check=False)  # noqa: S603
+        env = os.environ.copy()
+        if secrets:
+            env["DOCKER_BUILDKIT"] = "1"
+        result = subprocess.run(cmd, check=False, env=env)  # noqa: S603
         return result.returncode == 0
     except Exception as e:
         hud_console.error(f"Build error: {e}")
@@ -650,11 +659,14 @@ def build_environment(
     verbose: bool = False,
     env_vars: dict[str, str] | None = None,
     platform: str | None = None,
+    secrets: list[str] | None = None,
     remote_cache: str | None = None,
+    build_args: dict[str, str] | None = None,
 ) -> None:
     """Build a HUD environment and generate lock file."""
     hud_console = HUDConsole()
     env_vars = env_vars or {}
+    build_args = build_args or {}
     hud_console.header("HUD Environment Build")
 
     # Resolve directory
@@ -721,8 +733,9 @@ def build_environment(
         temp_tag,
         no_cache,
         verbose,
-        build_args=None,
+        build_args=build_args or None,
         platform=platform,
+        secrets=secrets,
         remote_cache=remote_cache,
     ):
         hud_console.error("Docker build failed")
@@ -1002,16 +1015,27 @@ def build_environment(
     if image_tag and image_tag not in [version_tag, latest_tag]:
         label_cmd.extend(["-t", image_tag])
 
+    # Add build args to final image build (same as initial build)
+    for key, value in build_args.items():
+        label_cmd.extend(["--build-arg", f"{key}={value}"])
+
+    # Add secrets to final image build (same as initial build)
+    for secret in secrets or []:
+        label_cmd.extend(["--secret", secret])
+
     label_cmd.append(str(env_dir))
 
     # Run rebuild using Docker's native output formatting
+    env = os.environ.copy()
+    if secrets:
+        env["DOCKER_BUILDKIT"] = "1"
     if verbose:
         # Show Docker's native output when verbose
-        result = subprocess.run(label_cmd, check=False)  # noqa: S603
+        result = subprocess.run(label_cmd, check=False, env=env)  # noqa: S603
     else:
         # Capture output for error reporting, but don't show unless it fails
         result = subprocess.run(  # noqa: S603
-            label_cmd, capture_output=True, text=True, check=False
+            label_cmd, capture_output=True, text=True, check=False, env=env
         )
 
     if result.returncode != 0:
@@ -1105,7 +1129,15 @@ def build_command(
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
     env_vars: dict[str, str] | None = None,
     platform: str | None = None,
+    secrets: list[str] | None = typer.Option(  # noqa: B008
+        None,
+        "--secret",
+        help=("Docker build secret (repeatable), e.g. --secret id=GITHUB_TOKEN,env=GITHUB_TOKEN"),
+    ),
     remote_cache: str | None = None,
+    build_args: dict[str, str] | None = None,
 ) -> None:
     """Build a HUD environment and generate lock file."""
-    build_environment(directory, tag, no_cache, verbose, env_vars, platform, remote_cache)
+    build_environment(
+        directory, tag, no_cache, verbose, env_vars, platform, secrets, remote_cache, build_args
+    )