hud-python 0.3.5__py3-none-any.whl → 0.4.1__py3-none-any.whl

hud/tools/types.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import ContentBlock, ImageContent, TextContent
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class EvaluationResult(BaseModel):
+    """Standard evaluation result format."""
+
+    reward: float = Field(default=0.0, description="Usually a value between 0.0 and 1.0")
+    done: bool = Field(default=False, description="Whether the task/episode is complete")
+    content: str | None = Field(default=None, description="Additional information")
+    info: dict[str, Any] = Field(default_factory=dict, description="Additional information")
+    isError: bool = Field(default=False, description="Whether the evaluation failed")
+
+    model_config = ConfigDict(extra="allow")
+
+
+class ContentResult(BaseModel):
+    """Represents the intermediate result of a tool execution.
+
+    Often useful for tools that need to return multiple types of content.
+    """
+
+    output: str | None = Field(default=None, description="Output text")
+    error: str | None = Field(default=None, description="Error message")
+    base64_image: str | None = Field(default=None, description="Base64-encoded image")
+    system: str | None = Field(default=None, description="System message")
+
+    def __add__(self, other: ContentResult) -> ContentResult:
+        def combine_fields(
+            field: str | None, other_field: str | None, concatenate: bool = True
+        ) -> str | None:
+            if field and other_field:
+                if concatenate:
+                    return field + other_field
+                raise ValueError("Cannot combine tool results")
+            return field or other_field
+
+        return ContentResult(
+            output=combine_fields(self.output, other.output),
+            error=combine_fields(self.error, other.error),
+            base64_image=combine_fields(self.base64_image, other.base64_image, False),
+            system=combine_fields(self.system, other.system),
+        )
+
+    def to_content_blocks(self) -> list[ContentBlock]:
+        """Helper method to convert ContentResult to content blocks.
+
+        Subclasses can use this when they work with ContentResult internally.
+
+        Args:
+            result: ContentResult to convert
+
+        Returns:
+            List of ContentBlock
+        """
+        blocks: list[ContentBlock] = []
+
+        if self.output:
+            blocks.append(TextContent(text=self.output, type="text"))
+        if self.error:
+            blocks.append(TextContent(text=self.error, type="text"))
+        if self.base64_image:
+            blocks.append(ImageContent(data=self.base64_image, mimeType="image/png", type="image"))
+        return blocks
+
+
+class ToolError(Exception):
+    """An error raised by a tool."""

hud/tools/utils.py

@@ -1,50 +1,50 @@
-from __future__ import annotations
-
-import asyncio
-import subprocess
-
-# Default timeout for running commands
-DEFAULT_TIMEOUT = 10.0
-
-
-async def run(
-    command: str | list[str],
-    input: str | None = None,
-    timeout: float | None = DEFAULT_TIMEOUT,  # noqa: ASYNC109
-) -> tuple[int, str, str]:
-    """
-    Run a command asynchronously and return the result.
-
-    Args:
-        command: Command to run (string or list of strings)
-        input: Optional input to send to stdin
-        timeout: Timeout in seconds
-
-    Returns:
-        Tuple of (return_code, stdout, stderr)
-    """
-    if isinstance(command, str):
-        proc = await asyncio.create_subprocess_shell(
-            command,
-            stdin=subprocess.PIPE if input else None,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-        )
-    else:
-        proc = await asyncio.create_subprocess_exec(
-            *command,
-            stdin=subprocess.PIPE if input else None,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-        )
-
-    stdout, stderr = await asyncio.wait_for(
-        proc.communicate(input=input.encode() if input else None), timeout=timeout
-    )
-
-    return proc.returncode or 0, stdout.decode(), stderr.decode()
-
-
-def maybe_truncate(text: str, max_length: int = 2048 * 10) -> str:
-    """Truncate output if too long."""
-    return text if len(text) <= max_length else text[:max_length] + "... (truncated)"
+from __future__ import annotations
+
+import asyncio
+import subprocess
+
+# Default timeout for running commands
+DEFAULT_TIMEOUT = 10.0
+
+
+async def run(
+    command: str | list[str],
+    input: str | None = None,
+    timeout: float | None = DEFAULT_TIMEOUT,  # noqa: ASYNC109
+) -> tuple[int, str, str]:
+    """
+    Run a command asynchronously and return the result.
+
+    Args:
+        command: Command to run (string or list of strings)
+        input: Optional input to send to stdin
+        timeout: Timeout in seconds
+
+    Returns:
+        Tuple of (return_code, stdout, stderr)
+    """
+    if isinstance(command, str):
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdin=subprocess.PIPE if input else None,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+    else:
+        proc = await asyncio.create_subprocess_exec(
+            *command,
+            stdin=subprocess.PIPE if input else None,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+
+    stdout, stderr = await asyncio.wait_for(
+        proc.communicate(input=input.encode() if input else None), timeout=timeout
+    )
+
+    return proc.returncode or 0, stdout.decode(), stderr.decode()
+
+
+def maybe_truncate(text: str, max_length: int = 2048 * 10) -> str:
+    """Truncate output if too long."""
+    return text if len(text) <= max_length else text[:max_length] + "... (truncated)"

hud/types.py

@@ -1,89 +1,136 @@
-from __future__ import annotations
-
-import enum
-from pathlib import Path
-from typing import Any, Literal, TypeAlias
-
-from pydantic import BaseModel
-
-
-class CustomGym(BaseModel):
-    """
-    Public environment specification with a dockerfile and controller.
-
-    If the location is remote, the env will be created on the server.
-    If the location is local, the env will be created locally via docker.
-
-    The dockerfile can be specified directly or automatically found in the controller_source_dir.
-    If neither is provided, an error will be raised during validation.
-    """
-
-    type: Literal["public"] = "public"
-    location: Literal["local", "remote"]
-    # A. If path, then it is a docker build context on the local computer.
-    #    If the location is local, docker build will be used to create the image.
-    #    If the location is remote, we will build the image remotely.
-    #    The controller will be automatically installed and kept in sync with local changes
-    #    as long as a pyproject.toml is present at the root of the folder.
-    # B. If string, then it is the uri of the docker image to use.
-    #    The controller must already be installed in the image.
-    image_or_build_context: str | Path
-    # host_config will be passed to the docker client when creating the environment.
-    # refer to official docker api documentation for available configs.
-    host_config: dict[str, Any] | None = None
-
-
-class MCPConfig(BaseModel):
-    """
-    MCP config for the environment.
-    """
-
-    type: Literal["mcp"] = "mcp"
-    config: dict[str, Any]
-
-
-class EnvironmentStatus(str, enum.Enum):
-    """
-    Status of the environment.
-
-    Attributes:
-        INITIALIZING: The environment is initializing
-        RUNNING: The environment is running
-        COMPLETED: The environment is completed
-        ERROR: The environment is in an error state
-    """
-
-    INITIALIZING = "initializing"
-    RUNNING = "running"
-    COMPLETED = "completed"
-    ERROR = "error"
-
-
-# Available HUD gyms
-ServerGym: TypeAlias = Literal["qa", "hud-browser", "OSWorld-Ubuntu", "docker"]
-
-# Gyms can be either custom or server-side
-Gym: TypeAlias = CustomGym | MCPConfig | ServerGym
-
-
-# Metadata keys for the environment.
-# partial: Whether the environment evaluator should give partial grades.
-# eval_model: The model to use for evaluation when running a VLM. Wraps langchain.
-# agent_name: The name of the agent that was used for running this task.
-ServerMetadataKeys: TypeAlias = Literal["partial", "eval_model", "agent_name"]
-MetadataKeys: TypeAlias = str | ServerMetadataKeys
-
-
-# Dictionary of sensitive data (only supported for hud-browser environments)
-# key: website name or page identifier
-# value: Dictionary of credentials for the sensitive data
-# Example:
-# {
-#     "google.com": {
-#         "google_username": "my_username",
-#         "google_password": "my_password"
-#     }
-# }
-# The agent only has access to the key of the credential, not the value. (i.e. google_username)
-# The value is only available to the environment. (i.e. my_username)
-SensitiveData: TypeAlias = dict[str, dict[str, str]]
+from __future__ import annotations
+
+import uuid
+from typing import Any, Literal
+
+from mcp.types import CallToolRequestParams, CallToolResult
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MCPToolCall(CallToolRequestParams):
+    """A tool call."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))  # Unique identifier for reference
+
+    def __str__(self) -> str:
+        response = f"Tool: {self.name}"
+        if self.arguments:
+            response += f"\nArguments: {self.arguments}"
+        return response
+
+
+class MCPToolResult(CallToolResult):
+    """A tool result."""
+
+    def __str__(self) -> str:
+        response = f"Content: {self.content}"
+        if self.structuredContent:
+            response += f"\nStructured Content: {self.structuredContent}"
+        if self.isError:
+            response += f"\nError: {self.isError}"
+        return response
+
+
+class AgentResponse(BaseModel):
+    """A model response in the conversation."""
+
+    # --- FUNCTIONAL ---
+    tool_calls: list[MCPToolCall] = Field(default_factory=list)
+    done: bool = Field(default=False)
+
+    # --- TELEMETRY [app.hud.so] ---
+    # Responses
+    content: str | None = Field(default=None)
+    reasoning: str | None = Field(default=None)
+    info: dict[str, Any] = Field(default_factory=dict)
+    isError: bool = Field(default=False)
+    raw: Any | None = Field(default=None)  # Include raw response for access to Choice objects
+
+    # Timestamps
+    start_timestamp: str | None = None
+    end_timestamp: str | None = None
+
+    def __str__(self) -> str:
+        response = ""
+        if self.reasoning:
+            response += f"Reasoning: {self.reasoning}\n"
+        if self.content:
+            response += f"Content: {self.content}\n"
+        if self.tool_calls:
+            response += f"""Tool Calls: {
+                ", ".join([f"{tc.name}: {tc.arguments}" for tc in self.tool_calls])
+            }"""
+        if self.raw:
+            response += f"Raw: {self.raw}"
+        return response
+
+
+class TraceStep(BaseModel):
+    """Canonical data for a single span (shared with telemetry)."""
+
+    # HUD identifiers
+    task_run_id: str | None = Field(default=None)
+    job_id: str | None = Field(default=None)
+
+    # Span category - can be any string, but "mcp" and "agent" are privileged on the platform
+    category: Literal["mcp", "agent"] | str = Field(default="mcp")  # noqa: PYI051
+
+    # Generic I/O fields - works for any category
+    request: Any | None = None
+    result: Any | None = None
+
+    # Generic span info
+    type: str = Field(default="CLIENT")
+
+    # Timestamps (optional, for local tracking)
+    start_timestamp: str | None = None
+    end_timestamp: str | None = None
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+
+class Trace(BaseModel):
+    """Unified result from agent execution (task or prompt).
+
+    Fields:
+    - done: Whether the run is complete
+    - reward: The reward for the run
+    - info: Additional metadata for the run
+    - content: The final content/response from the agent
+    - isError: Whether the execution resulted in an error
+    - trace: The steps taken in the run (empty if not tracing)
+    """
+
+    done: bool = Field(default=True)
+    reward: float = Field(default=0.0)
+    info: dict[str, Any] = Field(default_factory=dict)
+    content: str | None = Field(default=None)
+    isError: bool = Field(default=False)
+    trace: list[TraceStep] = Field(default_factory=list)
+
+    def append(self, step: TraceStep) -> None:
+        self.trace.append(step)
+
+    def populate_from_context(self) -> None:
+        """Populate trace steps from the current trace context if available.
+
+        This checks if we're executing within a hud.trace() context and
+        automatically populates the trace field with collected steps.
+        """
+        from hud.otel.context import get_current_task_run_id
+        from hud.telemetry.replay import get_trace
+
+        task_run_id = get_current_task_run_id()
+        if task_run_id:
+            collected_trace = get_trace(task_run_id)
+            if collected_trace:
+                self.trace = collected_trace.trace
+
+
+__all__ = [
+    "AgentResponse",
+    "MCPToolCall",
+    "MCPToolResult",
+    "Trace",
+    "TraceStep",
+]

hud/utils/__init__.py

@@ -1,16 +1,10 @@
-from __future__ import annotations
-
-from .common import ExecuteResult
-from .config import FunctionConfig, FunctionConfigs, expand_config
-from .deprecation import deprecated, emit_deprecation_warning
-from .telemetry import stream
-
-__all__ = [
-    "ExecuteResult",
-    "FunctionConfig",
-    "FunctionConfigs",
-    "deprecated",
-    "emit_deprecation_warning",
-    "expand_config",
-    "stream",
-]
+from __future__ import annotations
+
+from .design import HUDDesign, design
+from .telemetry import stream
+
+__all__ = [
+    "HUDDesign",
+    "design",
+    "stream",
+]

hud/utils/async_utils.py

@@ -0,0 +1,65 @@
+"""Async utilities for HUD SDK.
+
+This module provides utilities for running async code in various environments,
+including Jupyter notebooks and synchronous contexts.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+logger = logging.getLogger(__name__)
+
+
+def fire_and_forget(coro: Coroutine[Any, Any, Any], description: str = "task") -> None:
+    """Execute a coroutine in a fire-and-forget manner.
+
+    This function handles running async code in various contexts:
+    - When an event loop is already running (normal async context)
+    - When no event loop exists (sync context, some Jupyter setups)
+    - Gracefully handles interpreter shutdown
+
+    Args:
+        coro: The coroutine to execute
+        description: Description of the task for logging (e.g., "update job status")
+
+    Example:
+        fire_and_forget(
+            some_async_function(),
+            description="update status"
+        )
+    """
+    try:
+        # Try to get current event loop
+        loop = asyncio.get_running_loop()
+        # Schedule the coroutine
+        task = loop.create_task(coro)
+        # Add error handler to prevent unhandled exceptions
+        task.add_done_callback(lambda t: t.exception() if not t.cancelled() else None)
+    except RuntimeError:
+        # No running event loop (e.g., Jupyter without %autoawait, sync context)
+        try:
+            # Try to run in a thread as a fallback
+            def run_in_thread() -> None:
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                try:
+                    loop.run_until_complete(coro)
+                except Exception as e:
+                    # Suppress warnings about interpreter shutdown
+                    if "interpreter shutdown" not in str(e):
+                        logger.debug("Error in threaded %s: %s", description, e)
+
+            thread = threading.Thread(target=run_in_thread, daemon=True)
+            thread.start()
+        except Exception as e:
+            # If that fails too, just log and continue
+            # Special case: suppress "cannot schedule new futures after interpreter shutdown"
+            if "interpreter shutdown" not in str(e):
+                logger.debug("Could not %s - no event loop available: %s", description, e)

hud/utils/design.py

@@ -0,0 +1,168 @@
+"""HUD Design System - Consistent styling utilities for CLI output.
+
+This module provides a unified design system for HUD CLI commands,
+ensuring consistent colors, formatting, and visual hierarchy across
+all commands.
+
+Color Palette:
+- Gold (#c0960c): Primary brand color for headers and important elements
+- Black: Standard text and underlined links
+- Red: Errors and failures
+- Green: Success messages
+- Dim/Gray: Secondary information
+"""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+# HUD Brand Colors
+GOLD = "rgb(192,150,12)"  # #c0960c
+RED = "red"
+GREEN = "green"
+DIM = "dim"
+
+
+class HUDDesign:
+    """Design system for HUD CLI output."""
+
+    def __init__(self, console: Console | None = None, stderr: bool = False) -> None:
+        """Initialize the design system.
+
+        Args:
+            console: Rich console instance. Creates new one if not provided.
+            stderr: If True, output to stderr instead of stdout.
+        """
+        self.console = console or Console(stderr=stderr)
+
+    def header(self, title: str, icon: str = "🚀") -> None:
+        """Print a header panel with gold border.
+
+        Args:
+            title: The title text
+            icon: Optional emoji icon
+        """
+        self.console.print(Panel.fit(f"{icon} [bold]{title}[/bold]", border_style=GOLD))
+
+    def section_title(self, title: str) -> None:
+        """Print a section title in gold.
+
+        Args:
+            title: The section title
+        """
+        self.console.print(f"\n[bold {GOLD}]{title}[/bold {GOLD}]")
+
+    def success(self, message: str) -> None:
+        """Print a success message.
+
+        Args:
+            message: The success message
+        """
+        self.console.print(f"[{GREEN} not bold]✅ {message}[/{GREEN} not bold]")
+
+    def error(self, message: str) -> None:
+        """Print an error message.
+
+        Args:
+            message: The error message
+        """
+        self.console.print(f"[{RED} not bold]❌ {message}[/{RED} not bold]")
+
+    def warning(self, message: str) -> None:
+        """Print a warning message.
+
+        Args:
+            message: The warning message
+        """
+        self.console.print(f"[yellow]⚠️  {message}[/yellow]")
+
+    def info(self, message: str) -> None:
+        """Print an info message.
+
+        Args:
+            message: The info message
+        """
+        self.console.print(f"[default not bold]{message}[/default not bold]")
+
+    def dim_info(self, label: str, value: str) -> None:
+        """Print dimmed info with a label.
+
+        Args:
+            label: The label text
+            value: The value text
+        """
+        self.console.print(f"[{DIM}]{label}[/{DIM}] [default]{value}[/default]")
+
+    def link(self, url: str) -> None:
+        """Print an underlined link.
+
+        Args:
+            url: The URL to display
+        """
+        self.console.print(f"[default not bold underline]{url}[/default not bold underline]")
+
+    def json_config(self, json_str: str) -> None:
+        """Print JSON configuration with light theme.
+
+        Args:
+            json_str: JSON string to display
+        """
+        # Just print the JSON as plain text to avoid any syntax coloring
+        self.console.print(f"[default not bold]{json_str}[/default not bold]")
+
+    def key_value_table(self, data: dict[str, str], show_header: bool = False) -> None:
+        """Print a key-value table.
+
+        Args:
+            data: Dictionary of key-value pairs
+            show_header: Whether to show table header
+        """
+        table = Table(show_header=show_header, box=None, padding=(0, 1))
+        table.add_column("Key", style=DIM, no_wrap=True)
+        table.add_column("Value")
+
+        for key, value in data.items():
+            table.add_row(key, value)
+
+        self.console.print(table)
+
+    def progress_message(self, message: str) -> None:
+        """Print a progress message.
+
+        Args:
+            message: The progress message
+        """
+        self.console.print(f"[{DIM} not bold]{message}[/{DIM} not bold]")
+
+    def phase(self, phase_num: int, title: str) -> None:
+        """Print a phase header (for debug command).
+
+        Args:
+            phase_num: Phase number
+            title: Phase title
+        """
+        self.console.print(f"\n{'=' * 80}", style=GOLD)
+        self.console.print(f"[bold {GOLD}]PHASE {phase_num}: {title}[/bold {GOLD}]")
+        self.console.print(f"{'=' * 80}", style=GOLD)
+
+    def command(self, cmd: list[str]) -> None:
+        """Print a command being executed.
+
+        Args:
+            cmd: Command parts as list
+        """
+        self.console.print(f"[bold]$ {' '.join(cmd)}[/bold]")
+
+    def hint(self, hint: str) -> None:
+        """Print a hint message.
+
+        Args:
+            hint: The hint text
+        """
+        self.console.print(f"\n[yellow]💡 Hint: {hint}[/yellow]")
+
+
+# Global design instance for convenience
+design = HUDDesign()