hud-python 0.4.35__py3-none-any.whl → 0.4.37__py3-none-any.whl

hud/cli/utils/package_runner.py

@@ -0,0 +1,292 @@
+"""Run Python modules or commands as MCP servers.
+
+This module handles direct execution of MCP servers, including:
+- Python modules with an 'mcp' attribute
+- External commands via FastMCP proxy
+- Auto-reload functionality for development
+
+For Docker container execution, see hud dev command.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+import shlex
+import signal
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+
+async def run_package_as_mcp(
+    command: str | list[str],
+    transport: str = "stdio",
+    port: int = 8765,
+    verbose: bool = False,
+    reload: bool = False,
+    watch_paths: list[str] | None = None,
+    server_attr: str = "mcp",
+    **extra_kwargs: Any,
+) -> None:
+    """Run a command as an MCP server.
+
+    Can run:
+    - Python modules: 'controller' (imports and looks for mcp attribute)
+    - Python -m commands: 'python -m controller'
+    - Docker commands: 'docker run -it my-mcp-server'
+    - Any executable: './my-mcp-binary'
+
+    Args:
+        command: Command to run (string or list)
+        transport: Transport type ("stdio" or "http")
+        port: Port for HTTP transport
+        verbose: Enable verbose logging
+        reload: Enable auto-reload on file changes
+        watch_paths: Paths to watch for changes (defaults to ['.'])
+        **extra_kwargs: Additional arguments
+    """
+    # Set up logging
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.INFO)
+
+    # Handle reload mode
+    if reload:
+        if watch_paths is None:
+            watch_paths = ["."]
+
+        # Detect external command vs module reliably.
+        # If command is a string and contains spaces (e.g., "uv run python -m controller")
+        # treat as external command. Otherwise, detect common launchers or paths.
+        is_external_cmd = False
+        if isinstance(command, list):
+            is_external_cmd = True
+        elif isinstance(command, str):
+            stripped = command.strip()
+            if " " in stripped or any(
+                stripped.startswith(x)
+                for x in ["python", "uv ", "docker", "./", "/", ".\\", "C:\\"]
+            ):
+                is_external_cmd = True
+
+        if is_external_cmd:
+            # External command - pass command list directly
+            cmd_list = shlex.split(command) if isinstance(command, str) else command
+            run_with_reload(cmd_list, watch_paths, verbose)
+        else:
+            # Python module - use sys.argv approach
+            run_with_reload(None, watch_paths, verbose)
+        return
+
+    # Determine if it's a module import or a command
+    if isinstance(command, str) and not any(
+        command.startswith(x) for x in ["python", "docker", "./", "/", ".\\", "C:\\"]
+    ):
+        # Treat as Python module for backwards compatibility
+        logger.info("Importing module: %s", command)
+        module = importlib.import_module(command)
+
+        # Look for server attribute in the module
+        if not hasattr(module, server_attr):
+            logger.error(
+                "Module '%s' does not have an '%s' attribute (MCPServer instance)",
+                command,
+                server_attr,
+            )
+            sys.exit(1)
+
+        server = getattr(module, server_attr)
+
+        # Configure server options
+        run_kwargs = {
+            "transport": transport,
+            "show_banner": False,
+        }
+
+        if transport == "http":
+            # FastMCP expects port/path directly
+            run_kwargs["port"] = port
+            run_kwargs["path"] = "/mcp"
+
+        # Merge any extra kwargs
+        run_kwargs.update(extra_kwargs)
+
+        # Run the server
+        logger.info("Running %s on %s transport", server.name, transport)
+        await server.run_async(**run_kwargs)
+    else:
+        # Run as external command using shared proxy utility
+        # Parse command if string
+        cmd_list = shlex.split(command) if isinstance(command, str) else command
+
+        # Replace 'python' with the current interpreter to preserve venv
+        if cmd_list[0] == "python":
+            cmd_list[0] = sys.executable
+            logger.info("Replaced 'python' with: %s", sys.executable)
+
+        logger.info("Running command: %s", " ".join(cmd_list))
+
+        # Create MCP config for the command
+        config = {
+            "mcpServers": {
+                "default": {
+                    "command": cmd_list[0],
+                    "args": cmd_list[1:] if len(cmd_list) > 1 else [],
+                    # transport defaults to stdio
+                }
+            }
+        }
+
+        # Create proxy server
+        proxy = FastMCP.as_proxy(config, name=f"HUD Run - {cmd_list[0]}")
+
+        # Run the proxy
+        await proxy.run_async(
+            transport=transport if transport == "http" or transport == "stdio" else None,
+            port=port if transport == "http" else None,
+            show_banner=False,
+            **extra_kwargs,
+        )
+
+
+def run_with_reload(
+    target_func: Any,
+    watch_paths: list[str],
+    verbose: bool = False,
+) -> None:
+    """Run a function or command with file watching and auto-reload.
+
+    Args:
+        target_func: Function to run (sync) or command list
+        watch_paths: Paths to watch for changes
+        verbose: Enable verbose logging
+    """
+    try:
+        import watchfiles
+    except ImportError:
+        logger.error("watchfiles is required for --reload. Install with: pip install watchfiles")
+        sys.exit(1)
+
+    # Resolve watch paths
+    resolved_paths = []
+    for path_str in watch_paths:
+        path = Path(path_str).resolve()
+        if path.is_file():
+            # Watch the directory containing the file
+            resolved_paths.append(str(path.parent))
+        else:
+            resolved_paths.append(str(path))
+
+    def run_and_restart() -> None:
+        """Run the target function in a loop, restarting on file changes."""
+
+        process = None
+
+        def handle_signal(signum: int, frame: Any) -> None:
+            """Handle signals by terminating the subprocess."""
+            if process:
+                process.terminate()
+            sys.exit(0)
+
+        signal.signal(signal.SIGTERM, handle_signal)
+        signal.signal(signal.SIGINT, handle_signal)
+
+        stop_event = threading.Event()  # Define stop_event at the start
+
+        while True:
+            # Run the target function or command
+            if target_func is None:
+                # Use sys.argv approach for Python modules
+                child_args = [a for a in sys.argv[1:] if a != "--reload"]
+                # If first arg is already 'run', don't inject it again
+                if child_args and child_args[0] == "run":
+                    cmd = [sys.executable, "-m", "hud", *child_args]
+                else:
+                    cmd = [sys.executable, "-m", "hud", "run", *child_args]
+            elif isinstance(target_func, list):
+                # It's a command list
+                cmd = target_func
+            else:
+                # It's a callable - run it directly
+                target_func()
+                # Wait for file changes before restarting
+                stop_event.wait()
+                continue
+
+            if verbose:
+                logger.info("Starting process: %s", " ".join(cmd))
+
+            process = subprocess.Popen(cmd, env=os.environ)  # noqa: S603
+
+            # Watch for changes
+            try:
+                # Use a proper threading.Event for stop_event as required by watchfiles
+                stop_event = threading.Event()
+
+                def _wait_and_set(
+                    stop_event: threading.Event, process: subprocess.Popen[bytes]
+                ) -> None:
+                    try:
+                        if process is not None:
+                            process.wait()
+                    finally:
+                        stop_event.set()
+
+                threading.Thread(
+                    target=_wait_and_set, args=(stop_event, process), daemon=True
+                ).start()
+
+                for changes in watchfiles.watch(*resolved_paths, stop_event=stop_event):
+                    logger.info("Raw changes detected: %s", changes)
+                    # Filter for relevant file types
+                    relevant_changes = [
+                        (change_type, path)
+                        for change_type, path in changes
+                        if any(path.endswith(ext) for ext in [".py", ".json", ".toml", ".yaml"])
+                        and "__pycache__" not in path
+                        and not Path(path).name.startswith(".")
+                    ]
+
+                    if relevant_changes:
+                        logger.info("File changes detected, restarting server...")
+                        if verbose:
+                            for change_type, path in relevant_changes:
+                                logger.debug("  %s: %s", change_type, path)
+
+                        # Terminate the process
+                        if process is not None:
+                            process.terminate()
+                        try:
+                            if process is not None:
+                                process.wait(timeout=5)
+                        except subprocess.TimeoutExpired:
+                            if process is not None:
+                                process.kill()
+                                process.wait()
+
+                        # Brief pause before restart
+                        time.sleep(0.1)
+                        break
+                    else:
+                        logger.debug("Changes detected but filtered out: %s", changes)
+            except KeyboardInterrupt:
+                # Handle Ctrl+C gracefully
+                if process:
+                    process.terminate()
+                    process.wait()
+                break
+
+    # Always act as the parent. The child is launched without --reload,
+    # so it won't re-enter this function.
+
+    run_and_restart()

hud/cli/utils/remote_runner.py

@@ -293,7 +293,10 @@ def run_remote_server(
     if not api_key:
         api_key = settings.api_key
         if not api_key:
-            click.echo("❌ API key required. Set HUD_API_KEY env var or use --api-key", err=True)
+            click.echo(
+                "❌ API key required. Set HUD_API_KEY in your environment or run: hud set HUD_API_KEY=your-key-here",  # noqa: E501
+                err=True,
+            )
             sys.exit(1)
 
     # Build headers

hud/cli/utils/source_hash.py

@@ -0,0 +1,108 @@
+"""Utilities to compute a fast, deterministic source hash for environments.
+
+This intentionally focuses on the typical HUD environment layout and aims to be fast:
+- Always include: Dockerfile, pyproject.toml
+- Include directories: controller/, environment/, src/
+- Exclude common build/runtime caches and lock files
+
+Note: This is not a full Docker build context hash and does not parse .dockerignore.
+It is sufficient to detect meaningful changes for HUD environments quickly.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+EXCLUDE_DIRS = {
+    ".git",
+    ".venv",
+    "dist",
+    "build",
+    "node_modules",
+    "__pycache__",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+}
+
+EXCLUDE_FILE_SUFFIXES = {
+    ".pyc",
+    ".log",
+}
+
+EXCLUDE_FILES = {
+    "hud.lock.yaml",
+}
+
+INCLUDE_FILES = {"Dockerfile", "pyproject.toml"}
+INCLUDE_DIRS = {"controller", "environment"}
+
+
+def iter_source_files(root: Path) -> Iterable[Path]:
+    """Yield files to include in the source hash.
+
+    The order is not guaranteed; callers should sort for deterministic hashing.
+    """
+    # Always include top-level files if present
+    for name in INCLUDE_FILES:
+        p = root / name
+        if p.is_file():
+            yield p
+
+    # Include known directories
+    for d in INCLUDE_DIRS:
+        dp = root / d
+        if not dp.exists():
+            continue
+        for dirpath, dirnames, filenames in os.walk(dp):
+            # prune excluded dirs in-place
+            dirnames[:] = [dn for dn in dirnames if dn not in EXCLUDE_DIRS]
+            for fn in filenames:
+                if fn in EXCLUDE_FILES:
+                    continue
+                if any(fn.endswith(suf) for suf in EXCLUDE_FILE_SUFFIXES):
+                    continue
+                yield Path(dirpath) / fn
+
+
+def list_source_files(root: Path) -> list[Path]:
+    """Return a sorted list of files used for the source hash.
+
+    Sorting is by relative path to ensure deterministic ordering.
+    """
+    root = root.resolve()
+    files = list(iter_source_files(root))
+    files.sort(key=lambda p: str(p.resolve().relative_to(root)).replace("\\", "/"))
+    return files
+
+
+def compute_source_hash(directory: str | Path) -> str:
+    """Compute a deterministic SHA-256 hash over relevant source files.
+
+    Args:
+        directory: Environment directory root.
+
+    Returns:
+        Hex digest string.
+    """
+    root = Path(directory).resolve()
+    files = list_source_files(root)
+
+    hasher = hashlib.sha256()
+    for p in files:
+        rel = str(p.resolve().relative_to(root)).replace("\\", "/")
+        hasher.update(rel.encode("utf-8"))
+        with open(p, "rb") as f:
+            while True:
+                chunk = f.read(8192)
+                if not chunk:
+                    break
+                hasher.update(chunk)
+
+    return hasher.hexdigest()

hud/clients/base.py

@@ -139,7 +139,7 @@ class BaseHUDClient(AgentMCPClient):
                     raise HudAuthenticationError(
                         f'Sending authorization "{headers.get("Authorization", "")}", which may'
                         " be incomplete. Ensure HUD_API_KEY environment variable is set or send it"
-                        " as a header. You can get an API key at https://app.hud.so"
+                        " as a header. You can get an API key at https://hud.so"
                     )
             # Subclasses implement connection
             await self._connect(self._mcp_config)

hud/clients/fastmcp.py

@@ -95,7 +95,7 @@ class FastMCPHUDClient(BaseHUDClient):
                             raise RuntimeError(
                                 "Authentication failed for HUD API. "
                                 "Please ensure your HUD_API_KEY environment variable is set correctly."  # noqa: E501
-                                "You can get an API key at https://app.hud.so"
+                                "You can get an API key at https://hud.so"
                             ) from e
                     # Generic 401 error
                     raise RuntimeError(

hud/clients/mcp_use.py

@@ -5,19 +5,22 @@ from __future__ import annotations
 import logging
 import traceback
 from typing import Any
+from urllib.parse import urlparse
 
 from mcp import Implementation, types
 from mcp.shared.exceptions import McpError
 from mcp_use.client import MCPClient as MCPUseClient
 from mcp_use.session import MCPSession as MCPUseSession
+from mcp_use.types.http import HttpOptions
 from pydantic import AnyUrl
 
+from hud.settings import settings
 from hud.types import MCPToolCall, MCPToolResult
 from hud.utils.hud_console import HUDConsole
 from hud.version import __version__ as hud_version
 
 from .base import BaseHUDClient
-from .utils.mcp_use_retry import patch_all_sessions
+from .utils.retry_transport import create_retry_httpx_client
 
 logger = logging.getLogger(__name__)
 hud_console = HUDConsole(logger=logger)
@@ -30,7 +33,11 @@ class MCPUseHUDClient(BaseHUDClient):
         name="hud-mcp-use", title="hud MCP-use Client", version=hud_version
     )
 
-    def __init__(self, mcp_config: dict[str, dict[str, Any]] | None = None, **kwargs: Any) -> None:
+    def __init__(
+        self,
+        mcp_config: dict[str, dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> None:
         """
         Initialize MCP-use client.
 
@@ -51,6 +58,12 @@ class MCPUseHUDClient(BaseHUDClient):
             str, tuple[str, types.Tool, types.Tool]
         ] = {}  # server_name, original_tool, prefixed_tool
         self._client: Any | None = None  # Will be MCPUseClient when available
+        # Transport options for MCP-use (disable_sse_fallback, httpx_client_factory, etc.)
+        # Default to retry-enabled HTTPX client if factory not provided
+        self._http_options: HttpOptions = HttpOptions(
+            httpx_client_factory=create_retry_httpx_client,
+            disable_sse_fallback=True,
+        )
 
     async def _connect(self, mcp_config: dict[str, dict[str, Any]]) -> None:
         """Create all sessions for MCP-use client."""
@@ -58,19 +71,29 @@ class MCPUseHUDClient(BaseHUDClient):
             logger.warning("Client is already connected, cannot connect again")
             return
 
+        # If a server target matches HUD's MCP host and no auth is provided,
+        # inject the HUD API key as a Bearer token to avoid OAuth browser flow.
+        try:
+            hud_mcp_host = urlparse(settings.hud_mcp_url).netloc
+            if mcp_config and settings.api_key and hud_mcp_host:
+                for server_cfg in mcp_config.values():
+                    server_url = server_cfg.get("url")
+                    if not server_url:
+                        continue
+                    if urlparse(server_url).netloc == hud_mcp_host and not server_cfg.get("auth"):
+                        server_cfg["auth"] = settings.api_key
+        except Exception:
+            logger.warning("Failed to parse HUD MCP URL")
+
         config = {"mcpServers": mcp_config}
         if MCPUseClient is None:
             raise ImportError("MCPUseClient is not available")
-        self._client = MCPUseClient.from_dict(config)
+        self._client = MCPUseClient.from_dict(config, http_options=self._http_options)
         try:
             assert self._client is not None  # noqa: S101
             self._sessions = await self._client.create_all_sessions()
             hud_console.info(f"Created {len(self._sessions)} MCP sessions")
 
-            # Patch all sessions with retry logic
-            patch_all_sessions(self._sessions)
-            hud_console.debug("Applied retry logic to all MCP sessions")
-
             # Configure validation for all sessions based on client setting
             try:
                 for session in self._sessions.values():

hud/datasets/parallel.py

@@ -115,7 +115,9 @@ def _process_worker(
                     task_name = task_dict.get("prompt") or f"Task {index}"
 
                     # Use the job_id to group all tasks under the same job
-                    with hud.trace(task_name, job_id=job_id, task_id=task_dict.get("id")):
+                    raw_task_id = task_dict.get("id")
+                    safe_task_id = str(raw_task_id) if raw_task_id is not None else None
+                    with hud.trace(task_name, job_id=job_id, task_id=safe_task_id):
                         # Convert dict to Task
                         task = Task(**task_dict)
 

hud/datasets/runner.py

@@ -104,7 +104,10 @@ async def run_dataset(
                 task_name = task_dict.get("prompt") or f"Task {index}"
                 if custom_system_prompt and "system_prompt" not in task_dict:
                     task_dict["system_prompt"] = custom_system_prompt
-                with hud.trace(task_name, job_id=job_obj.id, task_id=task_dict.get("id")):
+                # Ensure task_id is a string for baggage propagation
+                raw_task_id = task_dict.get("id")
+                safe_task_id = str(raw_task_id) if raw_task_id is not None else None
+                with hud.trace(task_name, job_id=job_obj.id, task_id=safe_task_id):
                     # Convert dict to Task here, at trace level
                     task = Task(**task_dict)
 

hud/otel/config.py

@@ -111,7 +111,7 @@ def configure_telemetry(
         # Error if no exporters are configured
         raise ValueError(
             "No telemetry backend configured. Either:\n"
-            "1. Set HUD_API_KEY environment variable for HUD telemetry (https://app.hud.so)\n"
+            "1. Set HUD_API_KEY environment variable for HUD telemetry (https://hud.so)\n"
             "2. Use enable_otlp=True with configure_telemetry() for alternative backends (e.g., Jaeger)\n"  # noqa: E501
         )
     elif not settings.telemetry_enabled:

hud/otel/context.py

@@ -239,8 +239,25 @@ async def _update_task_status_async(
 
     try:
         data: dict[str, Any] = {"status": status}
-        if job_id:
-            data["job_id"] = job_id
+
+        # Resolve effective job_id from explicit param, OTel baggage, or current job context
+        effective_job_id: str | None = job_id
+        if not effective_job_id:
+            bj = baggage.get_baggage("hud.job_id")
+            if isinstance(bj, str) and bj:
+                effective_job_id = bj
+        if not effective_job_id:
+            try:
+                from hud.telemetry.job import get_current_job  # Local import to avoid cycles
+
+                current_job = get_current_job()
+                if current_job:
+                    effective_job_id = current_job.id
+            except Exception:
+                effective_job_id = None
+
+        if effective_job_id:
+            data["job_id"] = effective_job_id
         if error_message:
             data["error_message"] = error_message
 
@@ -302,8 +319,25 @@ def _update_task_status_sync(
 
     try:
         data: dict[str, Any] = {"status": status}
-        if job_id:
-            data["job_id"] = job_id
+
+        # Resolve effective job_id from explicit param, OTel baggage, or current job context
+        effective_job_id: str | None = job_id
+        if not effective_job_id:
+            bj = baggage.get_baggage("hud.job_id")
+            if isinstance(bj, str) and bj:
+                effective_job_id = bj
+        if not effective_job_id:
+            try:
+                from hud.telemetry.job import get_current_job  # Local import to avoid cycles
+
+                current_job = get_current_job()
+                if current_job:
+                    effective_job_id = current_job.id
+            except Exception:
+                effective_job_id = None
+
+        if effective_job_id:
+            data["job_id"] = effective_job_id
         if error_message:
             data["error_message"] = error_message
 
@@ -342,7 +376,7 @@ def _print_trace_url(task_run_id: str) -> None:
     if not (settings.telemetry_enabled and settings.api_key):
         return
 
-    url = f"https://app.hud.so/trace/{task_run_id}"
+    url = f"https://hud.so/trace/{task_run_id}"
     header = "🚀 See your agent live at:"
 
     # ANSI color codes
@@ -381,7 +415,7 @@ def _print_trace_complete_url(task_run_id: str, error_occurred: bool = False) ->
     if not (settings.telemetry_enabled and settings.api_key):
         return
 
-    url = f"https://app.hud.so/trace/{task_run_id}"
+    url = f"https://hud.so/trace/{task_run_id}"
 
     # ANSI color codes
     GREEN = "\033[92m"

hud/rl/buffer.py

@@ -155,6 +155,9 @@ class DatasetBuffer(Buffer[Task]):
                 f"This is because the number of training steps ({self.training_steps}) is not a multiple of the dataset size ({self.dataset_size})"  # noqa: E501
             )
 
+        if config.verbose:
+            hud_console.info(f"Sample task: {tasks[0]}")
+
         self.add_fill(tasks, self.number_of_tasks, config.training.shuffle_dataset)
 
     def _validate_tasks(self, tasks: list[Task]) -> list[Task]:

hud/rl/tests/test_learner.py

@@ -163,7 +163,7 @@ def test_skip_update_when_zero_adv(monkeypatch, learner_stub: GRPOLearner):
     # Return a zero scalar loss that *depends* on params so backward works,
     # but has zero gradients (no update signal).
     def _zero_loss(self, sample) -> torch.Tensor:
-        return sum(p.sum() for p in self.policy.parameters()) * 0.0
+        return sum(p.sum() for p in self.policy.parameters()) * 0.0  # type: ignore
 
     monkeypatch.setattr(GRPOLearner, "compute_loss", _zero_loss, raising=True)
 

hud/rl/vllm_adapter.py

@@ -36,7 +36,7 @@ class VLLMAdapter:
         headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
         payload = {"lora_name": adapter_name, "lora_path": adapter_path}
         # Implement exponential backoff for retrying the adapter load request.
-        max_retries = 5
+        max_retries = 8
         backoff_factor = 2
         delay = 1  # initial delay in seconds