hud-python 0.4.53__py3-none-any.whl → 0.4.55__py3-none-any.whl

hud/cli/flows/dev.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import base64
+import contextlib
+import json
+import logging
+from typing import Any
+
+from hud.settings import settings
+from hud.shared.requests import make_request
+from hud.utils.hud_console import hud_console
+
+logger = logging.getLogger(__name__)
+
+
+async def create_dynamic_trace(
+    *,
+    mcp_config: dict[str, dict[str, Any]],
+    build_status: bool,
+    environment_name: str,
+) -> str | None:
+    """
+    Create a dynamic trace for HUD dev sessions when running in HTTP mode.
+
+    Sends a POST to the HUD API with:
+      - mcp_config: points to the local MCP config (same as Cursor)
+      - build_status: True if Docker mode (built image), False if basic Python mode
+      - environment_name: Name of the environment/server/image
+
+    Returns the full URL to the live trace when successful, otherwise None.
+    """
+    api_base = settings.hud_api_url.rstrip("/")
+    # Endpoint TBD; use a sensible default path that the backend can wire up
+    url = f"{api_base}/dev/dynamic-traces"
+
+    payload = {
+        "mcp_config": mcp_config,
+        "build_status": bool(build_status),
+        "environment_name": environment_name,
+    }
+
+    # Best-effort; if missing API key, log and continue
+    api_key = settings.api_key
+    if not api_key:
+        logger.warning("Skipping dynamic trace creation; missing HUD_API_KEY")
+        return None
+
+    try:
+        resp = await make_request("POST", url=url, json=payload, api_key=api_key)
+        # New API returns an id; construct the URL as https://hud.so/trace/{id}
+        trace_id = None
+        if isinstance(resp, dict):
+            trace_id = resp.get("id")
+            if trace_id is None:
+                data = resp.get("data", {}) or {}
+                if isinstance(data, dict):
+                    trace_id = data.get("id")
+            # Backcompat: if url is provided directly
+            if not trace_id:
+                direct_url = resp.get("url") or (resp.get("data", {}) or {}).get("url")
+                if isinstance(direct_url, str) and direct_url:
+                    return direct_url
+
+        if isinstance(trace_id, str) and trace_id:
+            return f"https://hud.so/trace/{trace_id}"
+        return None
+    except Exception as e:
+        # Do not interrupt dev flow
+        try:
+            preview = json.dumps(payload)[:500]
+            logger.warning("Failed to create dynamic dev trace: %s | payload=%s", e, preview)
+        except Exception:
+            logger.warning("Failed to create dynamic dev trace: %s", e)
+        return None
+
+
+def show_dev_ui(
+    *,
+    live_trace_url: str,
+    server_name: str,
+    port: int,
+    cursor_deeplink: str,
+    is_docker: bool = False,
+) -> None:
+    """
+    Show the minimal dev UI with live trace link.
+
+    This is called only when we have a successful trace URL.
+    For full UI mode, the caller should use show_dev_server_info() directly.
+
+    Args:
+        live_trace_url: URL to the live trace
+        server_name: Name of the server/image
+        port: Port the server is running on
+        cursor_deeplink: Pre-generated Cursor deeplink URL
+        is_docker: Whether this is Docker mode (affects hot-reload message)
+    """
+    import webbrowser
+
+    from rich.panel import Panel
+
+    # Show header first
+    hud_console.header("HUD Development Server", icon="🚀")
+
+    # Try to open the live trace in the default browser
+    with contextlib.suppress(Exception):
+        # new=2 -> open in a new tab, if possible
+        webbrowser.open(live_trace_url, new=2)
+
+    # Show panel with just the link
+    # Center the link and style it: blue, bold, underlined
+    link_markup = f"[bold underline rgb(108,113,196)][link={live_trace_url}]{live_trace_url}[/link][/bold underline rgb(108,113,196)]"  # noqa: E501
+    # Use center alignment by surrounding with spaces via justify
+    from rich.align import Align
+
+    panel = Panel(
+        Align.center(link_markup),
+        title="🔗 Live Dev Trace",
+        border_style="rgb(192,150,12)",  # HUD gold
+        padding=(1, 2),
+    )
+    hud_console.console.print(panel)
+
+    # Show other info below
+    label = "Base image" if is_docker else "Server"
+    hud_console.info("")
+    hud_console.info(f"{hud_console.sym.ITEM} {label}: {server_name}")
+    hud_console.info(f"{hud_console.sym.ITEM} Cursor: {cursor_deeplink}")
+    hud_console.info("")
+    hud_console.info(f"{hud_console.sym.SUCCESS} Hot-reload enabled")
+    if is_docker:
+        hud_console.dim_info(
+            "",
+            "Container restarts on file changes (mounted volumes), "
+            "if changing tools run hud dev again",
+        )
+    hud_console.info("")
+
+
+def generate_cursor_deeplink(server_name: str, port: int) -> str:
+    """Generate a Cursor deeplink for the MCP server.
+
+    Args:
+        server_name: Name of the server
+        port: Port the server is running on
+
+    Returns:
+        Cursor deeplink URL
+    """
+    server_config = {"url": f"http://localhost:{port}/mcp"}
+    config_json = json.dumps(server_config, indent=2)
+    config_base64 = base64.b64encode(config_json.encode()).decode()
+    return (
+        f"cursor://anysphere.cursor-deeplink/mcp/install?name={server_name}&config={config_base64}"
+    )

hud/cli/flows/tasks.py

@@ -11,7 +11,7 @@ import yaml
 
 from hud.cli.push import push_environment
 from hud.cli.utils.docker import require_docker_running
-from hud.cli.utils.env_check import ensure_built, find_environment_dir
+from hud.cli.utils.env_check import find_environment_dir
 from hud.cli.utils.registry import extract_name_and_tag
 from hud.utils.hud_console import hud_console
 from hud.utils.tasks import load_tasks
@@ -56,7 +56,9 @@ def _validate_tasks(tasks: list[Task]) -> bool:
     return True
 
 
-def _ensure_pushed(env_dir: Path, lock_data: dict[str, Any]) -> dict[str, Any]:
+def _ensure_pushed(
+    env_dir: Path, lock_data: dict[str, Any], check_docker: bool = True
+) -> dict[str, Any]:
     """Ensure the environment is pushed to a registry; return updated lock data."""
     pushed = bool(lock_data.get("push"))
     if not pushed:
@@ -64,7 +66,8 @@ def _ensure_pushed(env_dir: Path, lock_data: dict[str, Any]) -> dict[str, Any]:
         if not hud_console.confirm("Push to a registry now (runs 'hud push')?", default=True):
             raise typer.Exit(1)
         # Check Docker availability before attempting a push
-        require_docker_running()
+        if check_docker:
+            require_docker_running()
 
         # If Docker or login is not configured, the push function will fail and halt.
         push_environment(str(env_dir), yes=True)
@@ -293,9 +296,24 @@ def convert_tasks_to_remote(tasks_file: str) -> str:
         hud_console.hint("Ensure you're in or near your environment folder before running 'hud rl'")
         raise typer.Exit(1)
 
-    # Ensure built and pushed
-    lock_data = ensure_built(env_dir, interactive=True)
-    lock_data = _ensure_pushed(env_dir, lock_data)
+    # For convert command, we don't need Docker running - just check for lock file
+    # This avoids showing Docker-related messages during conversion
+    lock_path = env_dir / "hud.lock.yaml"
+    if not lock_path.exists():
+        hud_console.error("No hud.lock.yaml found. The environment needs to be built first.")
+        hud_console.info("Run 'hud build' in the environment directory to build it.")
+        raise typer.Exit(1)
+
+    # Load lock data directly
+    try:
+        with open(lock_path) as f:
+            lock_data: dict[str, Any] = yaml.safe_load(f) or {}
+    except Exception as e:
+        hud_console.error(f"Failed to read hud.lock.yaml: {e}")
+        raise typer.Exit(1) from e
+
+    # Check if pushed - don't check Docker for convert command
+    lock_data = _ensure_pushed(env_dir, lock_data, check_docker=False)
 
     # Derive remote image name org/name:tag
     remote_image = _derive_remote_image(lock_data)
@@ -387,8 +405,11 @@ def convert_tasks_to_remote(tasks_file: str) -> str:
             f"Detected env vars in .env that look like API keys: {names_preview}.\n"
             "Include them as remote headers (values will be ${VAR} placeholders)?"
         )
-        if hud_console.confirm(prompt, default=True):
-            all_detected.update(missing)
+        if not hud_console.confirm(prompt, default=True):
+            # User cancelled - exit without creating the file
+            hud_console.info("Conversion cancelled by user")
+            raise typer.Exit(0)
+        all_detected.update(missing)
 
     # Final set of env vars to convert to headers
     provided_keys = all_detected
@@ -461,6 +482,5 @@ def convert_tasks_to_remote(tasks_file: str) -> str:
         f.write("\n")
 
     hud_console.success(f"Created remote tasks file: {remote_path.name}")
-    hud_console.hint("Proceeding with RL training on the remote environment")
 
     return str(remote_path)

hud/cli/tests/test_eval.py

@@ -11,7 +11,7 @@ from hud.cli.eval import (
     build_agent,
     run_single_task,
 )
-from hud.types import Task, Trace
+from hud.types import AgentType, Task, Trace
 
 
 class TestBuildAgent:
@@ -26,7 +26,7 @@ class TestBuildAgent:
             mock_runner.return_value = mock_instance
 
             # Test with verbose=False
-            result = build_agent("integration_test", verbose=False)
+            result = build_agent(AgentType.INTEGRATION_TEST, verbose=False)
 
             mock_runner.assert_called_once_with(verbose=False)
             assert result == mock_instance
@@ -40,7 +40,7 @@ class TestBuildAgent:
             mock_runner.return_value = mock_instance
 
             # Test with verbose=False
-            result = build_agent("claude", verbose=False)
+            result = build_agent(AgentType.CLAUDE, verbose=False)
 
             mock_runner.assert_called_once_with(model="claude-sonnet-4-20250514", verbose=False)
             assert result == mock_instance
@@ -55,7 +55,7 @@ class TestBuildAgent:
 
             # Test with verbose=False
             result = build_agent(
-                "claude",
+                AgentType.CLAUDE,
                 model="claude-sonnet-4-20250514",
                 allowed_tools=["act"],
                 verbose=True,
@@ -97,7 +97,7 @@ class TestRunSingleTask:
             patch("hud.cli.eval.find_environment_dir", return_value=None),
             patch("hud.cli.eval.hud.trace"),
         ):
-            await run_single_task("test.json", agent_type="integration_test", max_steps=10)
+            await run_single_task("test.json", agent_type=AgentType.INTEGRATION_TEST, max_steps=10)
 
             # Verify agent.run was called with the task containing agent_config
             mock_agent.run.assert_called_once()
@@ -119,7 +119,7 @@ class TestRunSingleTask:
             mock_grouped.return_value = [{"task": mock_task, "rewards": [1.0, 0.5]}]
 
             await run_single_task(
-                "test.json", agent_type="integration_test", group_size=3, max_steps=10
+                "test.json", agent_type=AgentType.INTEGRATION_TEST, group_size=3, max_steps=10
             )
 
             # Verify run_tasks_grouped was called with correct group_size

hud/cli/utils/docker.py

@@ -308,7 +308,10 @@ def require_docker_running() -> None:
             "Is Docker running? Open Docker Desktop and wait until it reports 'Running'"
         )
         raise typer.Exit(1) from e
-    except Exception as e:
-        hud_console.error(f"Docker check failed: {e}")
+    except typer.Exit:
+        # Propagate cleanly without extra noise; hints already printed above
+        raise
+    except Exception:
+        # Unknown failure - keep output minimal and avoid stack traces
         hud_console.hint("Is the Docker daemon running?")
-        raise typer.Exit(1) from e
+        raise typer.Exit(1)  # noqa: B904

hud/clients/base.py

@@ -146,7 +146,7 @@ class BaseHUDClient(AgentMCPClient):
         except HudException:
             raise
         except Exception as e:
-            # Auto-converts to appropriate HUD exception type with hints
+            hud_console.error(f"Failed to initialize MCP client: {e}")
             raise HudException from e
 
         # Common hud behavior - fetch telemetry
@@ -333,7 +333,7 @@ class BaseHUDClient(AgentMCPClient):
             tool_info = {
                 "name": tool.name,
                 "description": tool.description,
-                "input_schema": tool.inputSchema,
+                "inputSchema": tool.inputSchema,
             }
             analysis["tools"].append(tool_info)
 

hud/otel/context.py

@@ -6,6 +6,7 @@ User-facing APIs are in hud.telemetry.
 
 from __future__ import annotations
 
+import contextlib
 import contextvars
 import logging
 from contextlib import contextmanager
@@ -232,6 +233,8 @@ async def _update_task_status_async(
     error_message: str | None = None,
     trace_name: str | None = None,
     task_id: str | None = None,
+    group_id: str | None = None,
+    extra_metadata: dict[str, Any] | None = None,
 ) -> None:
     """Async task status update."""
     if not settings.telemetry_enabled:
@@ -271,12 +274,20 @@ async def _update_task_status_async(
         metadata["mcp_tool_steps"] = get_mcp_tool_steps()
         metadata["agent_steps"] = get_agent_steps()
 
+        # Merge any extra metadata provided by callers (e.g., task config summaries)
+        if extra_metadata:
+            with contextlib.suppress(Exception):
+                metadata.update(extra_metadata)
+
         if metadata:
             data["metadata"] = metadata
 
         if task_id:
             data["task_id"] = task_id
 
+        if group_id:
+            data["group_id"] = group_id
+
         await make_request(
             method="POST",
             url=f"{settings.hud_telemetry_url}/trace/{task_run_id}/status",
@@ -297,10 +308,21 @@ def _fire_and_forget_status_update(
     error_message: str | None = None,
     trace_name: str | None = None,
     task_id: str | None = None,
+    group_id: str | None = None,
+    extra_metadata: dict[str, Any] | None = None,
 ) -> None:
     """Fire and forget status update - works in any context including Jupyter."""
     fire_and_forget(
-        _update_task_status_async(task_run_id, status, job_id, error_message, trace_name, task_id),
+        _update_task_status_async(
+            task_run_id,
+            status,
+            job_id,
+            error_message,
+            trace_name,
+            task_id,
+            group_id,
+            extra_metadata,
+        ),
         f"update task {task_run_id} status to {status}",
     )
 
@@ -312,6 +334,8 @@ def _update_task_status_sync(
     error_message: str | None = None,
     trace_name: str | None = None,
     task_id: str | None = None,
+    group_id: str | None = None,
+    extra_metadata: dict[str, Any] | None = None,
 ) -> None:
     """Synchronous task status update."""
     if not settings.telemetry_enabled:
@@ -351,12 +375,20 @@ def _update_task_status_sync(
         metadata["mcp_tool_steps"] = get_mcp_tool_steps()
         metadata["agent_steps"] = get_agent_steps()
 
+        # Merge any extra metadata provided by callers
+        if extra_metadata:
+            with contextlib.suppress(Exception):
+                metadata.update(extra_metadata)
+
         if metadata:
             data["metadata"] = metadata
 
         if task_id:
             data["task_id"] = task_id
 
+        if group_id:
+            data["group_id"] = group_id
+
         make_request_sync(
             method="POST",
             url=f"{settings.hud_telemetry_url}/trace/{task_run_id}/status",
@@ -447,10 +479,12 @@ class trace:
         attributes: dict[str, Any] | None = None,
         job_id: str | None = None,
         task_id: str | None = None,
+        group_id: str | None = None,
     ) -> None:
         self.task_run_id = task_run_id
         self.job_id = job_id
         self.task_id = task_id
+        self.group_id = group_id
         self.is_root = is_root
         self.span_name = span_name
         self.attributes = attributes or {}
@@ -473,6 +507,8 @@ class trace:
             ctx = baggage.set_baggage("hud.job_id", self.job_id, context=ctx)
         if self.task_id:
             ctx = baggage.set_baggage("hud.task_id", self.task_id, context=ctx)
+        if self.group_id:
+            ctx = baggage.set_baggage("hud.group_id", self.group_id, context=ctx)
         self._otel_token = context.attach(ctx)
 
         # Start a span as current
@@ -486,6 +522,8 @@ class trace:
             span_attrs["hud.job_id"] = self.job_id
         if self.task_id:
             span_attrs["hud.task_id"] = self.task_id
+        if self.group_id:
+            span_attrs["hud.group_id"] = self.group_id
 
         # Use start_as_current_span context manager
         self._span_manager = tracer.start_as_current_span(
@@ -502,6 +540,7 @@ class trace:
                 job_id=self.job_id,
                 trace_name=self.span_name,
                 task_id=self.task_id,
+                group_id=self.group_id,
             )
             # Print the nice trace URL box (only if not part of a job)
             if not self.job_id:
@@ -528,6 +567,7 @@ class trace:
                     error_message=str(exc_val),
                     trace_name=self.span_name,
                     task_id=self.task_id,
+                    group_id=self.group_id,
                 )
                 # Print error completion message (only if not part of a job)
                 if not self.job_id:
@@ -540,6 +580,7 @@ class trace:
                     job_id=self.job_id,
                     trace_name=self.span_name,
                     task_id=self.task_id,
+                    group_id=self.group_id,
                 )
                 # Print success completion message (only if not part of a job)
                 if not self.job_id:

hud/server/server.py

@@ -311,11 +311,35 @@ class MCPServer(FastMCP):
         if transport is None:
             transport = "stdio"
 
-        # Register HTTP helpers for HTTP transport
+        # Register HTTP helpers and CORS for HTTP transport
         if transport in ("http", "sse"):
             self._register_hud_helpers()
             logger.info("Registered HUD helper endpoints at /hud/*")
 
+            # Add CORS middleware if not already provided
+            from starlette.middleware import Middleware
+            from starlette.middleware.cors import CORSMiddleware
+
+            # Get or create middleware list
+            middleware = transport_kwargs.get("middleware", [])
+            if isinstance(middleware, list):
+                # Check if CORS is already configured
+                has_cors = any(
+                    isinstance(m, Middleware) and m.cls == CORSMiddleware for m in middleware
+                )
+                if not has_cors:
+                    # Add CORS with permissive defaults for dev
+                    cors_middleware = Middleware(
+                        CORSMiddleware,
+                        allow_origins=["*"],
+                        allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+                        allow_headers=["*"],
+                        expose_headers=["Mcp-Session-Id"],
+                    )
+                    middleware = [cors_middleware, *middleware]
+                    transport_kwargs["middleware"] = middleware
+                    logger.info("Added CORS middleware for browser compatibility")
+
         try:
             await super().run_async(
                 transport=transport, show_banner=show_banner, **transport_kwargs
@@ -506,9 +530,11 @@ class MCPServer(FastMCP):
                         return str(obj)
 
                     serialized = serialize_obj(result)
-                    return JSONResponse({"success": True, "result": serialized})
+                    # Return the serialized CallToolResult directly (no wrapper)
+                    return JSONResponse(serialized)
                 except Exception as e:
-                    return JSONResponse({"success": False, "error": str(e)}, status_code=400)
+                    # Return a simple error object
+                    return JSONResponse({"error": str(e)}, status_code=400)
 
             return tool_endpoint
 

hud/settings.py

@@ -70,6 +70,12 @@ class Settings(BaseSettings):
         validation_alias="HUD_RL_URL",
     )
 
+    hud_api_url: str = Field(
+        default="https://api.hud.so",
+        description="Base URL for the HUD API server",
+        validation_alias="HUD_API_URL",
+    )
+
     api_key: str | None = Field(
         default=None,
         description="API key for authentication with the HUD API",

hud/telemetry/async_context.py

@@ -81,14 +81,16 @@ class AsyncTrace:
         attrs: dict[str, Any] | None = None,
         job_id: str | None = None,
         task_id: str | None = None,
+        group_id: str | None = None,
     ) -> None:
         self.name = name
         self.root = root
         self.attrs = attrs or {}
         self.job_id = job_id
         self.task_id = task_id
+        self.group_id = group_id
         self.task_run_id = str(uuid.uuid4())
-        self.trace_obj = Trace(self.task_run_id, name, job_id, task_id)
+        self.trace_obj = Trace(self.task_run_id, name, job_id, task_id, group_id)
         self._otel_trace = None
 
     async def __aenter__(self) -> Trace:
@@ -104,6 +106,7 @@ class AsyncTrace:
             attributes=self.attrs,
             job_id=self.job_id,
             task_id=self.task_id,
+            group_id=self.group_id,
         )
         self._otel_trace.__enter__()
 
@@ -116,6 +119,7 @@ class AsyncTrace:
                     job_id=self.job_id,
                     trace_name=self.name,
                     task_id=self.task_id,
+                    group_id=self.group_id,
                 ),
                 name=f"trace-status-{self.task_run_id[:8]}",
             )
@@ -146,6 +150,7 @@ class AsyncTrace:
                     error_message=str(exc_val) if exc_val else None,
                     trace_name=self.name,
                     task_id=self.task_id,
+                    group_id=self.group_id,
                 ),
                 name=f"trace-status-{self.task_run_id[:8]}-{status}",
             )
@@ -264,6 +269,7 @@ def async_trace(
     attrs: dict[str, Any] | None = None,
     job_id: str | None = None,
     task_id: str | None = None,
+    group_id: str | None = None,
 ) -> AsyncTrace:
     """Create an async trace context for telemetry tracking.
 
@@ -277,6 +283,7 @@ def async_trace(
         attrs: Additional attributes to attach to the trace
         job_id: Optional job ID to associate with this trace
         task_id: Optional task ID for custom task identifiers
+        group_id: Optional group ID to associate with this trace
 
     Returns:
         AsyncTrace context manager
@@ -292,7 +299,14 @@ def async_trace(
         Use this async version only in high-concurrency scenarios (200+ parallel
         tasks) or when writing custom async evaluation frameworks.
     """
-    return AsyncTrace(name, root=root, attrs=attrs, job_id=job_id, task_id=task_id)
+    return AsyncTrace(
+        name,
+        root=root,
+        attrs=attrs,
+        job_id=job_id,
+        task_id=task_id,
+        group_id=group_id if group_id else str(uuid.uuid4()),
+    )
 
 
 def async_job(

hud/telemetry/trace.py

@@ -34,11 +34,13 @@ class Trace:
         name: str,
         job_id: str | None = None,
         task_id: str | None = None,
+        group_id: str | None = None,
     ) -> None:
         self.id = trace_id
         self.name = name
         self.job_id = job_id
         self.task_id = task_id
+        self.group_id = group_id
         self.created_at = datetime.now(UTC)
 
     async def log(self, metrics: dict[str, Any]) -> None:
@@ -93,6 +95,7 @@ def trace(
     attrs: dict[str, Any] | None = None,
     job_id: str | None = None,
     task_id: str | None = None,
+    group_id: str | None = None,
 ) -> Generator[Trace, None, None]:
     """Start a HUD trace context for telemetry tracking.
 
@@ -104,6 +107,7 @@ def trace(
         attrs: Additional attributes to attach to the trace
         job_id: Optional job ID to associate with this trace
         task_id: Optional task ID (for custom task identifiers)
+        group_id: Optional group ID to associate with this trace
 
     Yields:
         Trace: The trace object with logging capabilities
@@ -143,7 +147,7 @@ def trace(
         task_run_id = str(uuid.uuid4())
 
     # Create trace object
-    trace_obj = Trace(task_run_id, name, job_id, task_id)
+    trace_obj = Trace(task_run_id, name, job_id, task_id, group_id)
 
     # Delegate to OpenTelemetry implementation
     with OtelTrace(
@@ -153,5 +157,6 @@ def trace(
         attributes=attrs or {},
         job_id=job_id,
         task_id=task_id,
+        group_id=group_id,
     ):
         yield trace_obj

hud/types.py

@@ -5,6 +5,7 @@ import json
 import logging
 import uuid
 from collections import defaultdict
+from enum import Enum
 from string import Template
 from typing import Any, Literal
 
@@ -21,6 +22,14 @@ logger = logging.getLogger(__name__)
 _missing_api_key_error_logged: bool = False
 
 
+class AgentType(str, Enum):
+    CLAUDE = "claude"
+    OPENAI = "openai"
+    VLLM = "vllm"
+    LITELLM = "litellm"
+    INTEGRATION_TEST = "integration_test"
+
+
 class Task(BaseModel):
     """
     A task configuration that can be used to create a task.
@@ -325,6 +334,7 @@ class Trace(BaseModel):
 
 __all__ = [
     "AgentResponse",
+    "AgentType",
     "MCPToolCall",
     "MCPToolResult",
     "Trace",