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

hud/tools/helper/server_initialization.py

@@ -1,115 +0,0 @@
-"""Helper for MCP server initialization with progress notifications.
-
-Example:
-    ```python
-    from hud.tools.helper import mcp_intialize_wrapper
-
-
-    @mcp_intialize_wrapper
-    async def initialize_environment(session=None, progress_token=None):
-        # Send progress if available
-        if session and progress_token:
-            await session.send_progress_notification(
-                progress_token=progress_token, progress=0, total=100, message="Starting services..."
-            )
-
-        # Your initialization code works with or without session
-        start_services()
-
-
-    # Create and run server - initialization happens automatically
-    mcp = FastMCP("My Server")
-    mcp.run()
-    ```
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-import mcp.types as types
-from mcp.server.session import ServerSession
-
-if TYPE_CHECKING:
-    from collections.abc import Awaitable, Callable
-
-    from mcp.shared.session import RequestResponder
-
-# Store the original _received_request method
-_original_received_request = ServerSession._received_request
-_init_function: Callable | None = None
-_initialized = False
-
-
-async def _patched_received_request(
-    self: ServerSession, responder: RequestResponder[types.ClientRequest, types.ServerResult]
-) -> types.ServerResult | None:
-    """Intercept initialization to run custom setup with progress notifications."""
-    global _initialized, _init_function
-
-    # Check if this is an initialization request
-    if isinstance(responder.request.root, types.InitializeRequest):
-        params = responder.request.root.params
-        # Extract progress token if present
-        progress_token = None
-        if hasattr(params, "meta") and params.meta and hasattr(params.meta, "progressToken"):
-            progress_token = params.meta.progressToken
-
-        # Run our initialization function if provided and not already done
-        if _init_function and not _initialized:
-            try:
-                await _init_function(session=self, progress_token=progress_token)
-                ServerSession._received_request = _original_received_request
-            except Exception as e:
-                if progress_token:
-                    await self.send_progress_notification(
-                        progress_token=progress_token,
-                        progress=0,
-                        total=100,
-                        message=f"Initialization failed: {e!s}",
-                    )
-                raise
-
-    # Call the original handler to send the InitializeResult
-    result = await _original_received_request(self, responder)
-    _initialized = True
-
-    return result
-
-
-def mcp_intialize_wrapper(
-    init_function: Callable[[ServerSession | None, str | None], Awaitable[None]] | None = None,
-) -> Callable:
-    """Decorator to enable progress notifications during MCP server initialization.
-
-    Your init function receives optional session and progress_token parameters.
-    If provided, use them to send progress updates. If not, the function still works.
-
-    Usage:
-        @mcp_intialize_wrapper
-        async def initialize(session=None, progress_token=None):
-            if session and progress_token:
-                await session.send_progress_notification(...)
-            # Your init code here
-
-    Must be applied before creating FastMCP instance or calling mcp.run().
-    """
-    global _init_function
-
-    def decorator(func: Callable[[ServerSession | None, str | None], Awaitable[None]]) -> Callable:
-        global _init_function
-        # Store the initialization function
-        _init_function = func
-
-        # Apply the monkey patch if not already applied
-        if ServerSession._received_request != _patched_received_request:
-            ServerSession._received_request = _patched_received_request  # type: ignore[assignment]
-
-        return func
-
-    # If called with a function directly
-    if init_function is not None:
-        return decorator(init_function)
-
-    # If used as @decorator
-    return decorator

hud/tools/helper/utils.py

@@ -1,58 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import inspect
-from functools import wraps
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from collections.abc import Callable
-
-    from mcp.server.fastmcp import FastMCP
-
-
-def register_instance_tool(mcp: FastMCP, name: str, instance: Any) -> Callable[..., Any]:
-    """Register ``instance.__call__`` as a FastMCP tool.
-
-    Parameters
-    ----------
-    mcp:
-        A :class:`mcp.server.fastmcp.FastMCP` instance.
-    name:
-        Public tool name.
-    instance:
-        Object with an ``async def __call__`` (or sync) implementing the tool.
-    """
-
-    if inspect.isclass(instance):
-        class_name = instance.__name__
-        raise TypeError(
-            f"register_instance_tool() expects an instance, but got class '{class_name}'. "
-            f"Use: register_instance_tool(mcp, '{name}', {class_name}()) "
-            f"Not: register_instance_tool(mcp, '{name}', {class_name})"
-        )
-
-    call_fn = instance.__call__
-    sig = inspect.signature(call_fn)
-
-    # Remove *args/**kwargs so Pydantic doesn't treat them as required fields
-    from typing import Any as _Any
-
-    filtered = [
-        p.replace(kind=p.POSITIONAL_OR_KEYWORD, annotation=_Any)
-        for p in sig.parameters.values()
-        if p.kind not in (p.VAR_POSITIONAL, p.VAR_KEYWORD)
-    ]
-
-    public_sig = inspect.Signature(parameters=filtered, return_annotation=_Any)
-
-    @wraps(call_fn)
-    async def _wrapper(*args: Any, **kwargs: Any) -> Any:  # type: ignore[override]
-        result = call_fn(*args, **kwargs)
-        if asyncio.iscoroutine(result):
-            result = await result
-        return result
-
-    _wrapper.__signature__ = public_sig  # type: ignore[attr-defined]
-
-    return mcp.tool(name=name)(_wrapper)

hud/trajectory.py

@@ -1,94 +0,0 @@
-# ruff: noqa: T201
-from __future__ import annotations
-
-import datetime
-
-from pydantic import BaseModel, Field
-
-from .adapters.common.types import LogType
-
-
-class TrajectoryStep(BaseModel):
-    """Model representing a single task run's trajectory information."""
-
-    observation_url: str | None = None
-    observation_text: str | None = None
-    actions: list[dict]
-    logs: LogType | None = None
-    start_timestamp: str | None = None
-    end_timestamp: str | None = None
-
-
-class Trajectory(BaseModel):
-    """Model representing a single task run's trajectory information."""
-
-    id: str
-    reward: float | None = None
-    logs: str | None = None
-    error: str | None = None
-    trajectory: list[TrajectoryStep] = Field(default_factory=list)
-
-    def display(self) -> None:
-        try:
-            from IPython.display import HTML, Markdown, display
-        except ImportError:
-            raise ImportError("IPython is required for trajectory display") from None
-
-        trajectory_start_timestamp_str = self.trajectory[0].start_timestamp
-        t_start_dt = (
-            datetime.datetime.fromisoformat(trajectory_start_timestamp_str.replace("Z", "+00:00"))
-            if trajectory_start_timestamp_str
-            else None
-        )
-        for i, step in enumerate(self.trajectory):
-            # Use Markdown for better step separation in Jupyter
-            display(Markdown(f"### Step {i + 1}"))
-
-            # Observation Image
-            if step.observation_url:
-                try:
-                    # Display in Jupyter/IPython environment using HTML
-                    display(Markdown("**Observation Image:**"))
-                    display(HTML(f'<img src="{step.observation_url}" style="max-width:100%;"/>'))
-                    display(Markdown(f"[Image Link]({step.observation_url})"))
-                except Exception as e:
-                    print(f"    [Error processing image: {e}]")
-            elif not step.observation_text:  # Only print if no image AND no text
-                print("    No visual or text observation provided.")
-
-            # Observation Text
-            if step.observation_text:
-                print(f"    Observation Text: {step.observation_text}")
-
-            # Actions
-            print(f"\n    Actions: {step.actions}")  # Added newline for spacing
-
-            # Duration
-            duration_str = "N/A"
-            step_start_timestamp = self.trajectory[i].start_timestamp
-            step_end_timestamp = self.trajectory[i].end_timestamp
-            if step_start_timestamp and step_end_timestamp and t_start_dt:
-                try:
-                    # Attempt to parse timestamps (assuming ISO format)
-                    start_dt = datetime.datetime.fromisoformat(
-                        step_start_timestamp.replace("Z", "+00:00")
-                    )
-                    end_dt = datetime.datetime.fromisoformat(
-                        step_end_timestamp.replace("Z", "+00:00")
-                    )
-                    duration = end_dt - start_dt
-                    total_seconds = duration.total_seconds()
-                    minutes = int(total_seconds // 60)
-                    seconds = total_seconds % 60
-                    duration_str = f"{minutes}m {seconds:.2f}s"
-
-                    # Calculate the total duration up to this step
-                    total_duration = end_dt - t_start_dt
-                    total_minutes = int(total_duration.total_seconds() // 60)
-                    total_seconds = total_duration.total_seconds() % 60
-                    total_duration_str = f"{total_minutes}m {total_seconds:.2f}s"
-                except ValueError:
-                    duration_str = "Error parsing timestamps"  # Handle potential format issues
-            print(f"    Step Duration: {duration_str}")
-            print(f"    Total Duration: {total_duration_str}")
-            display(Markdown("---"))  # Use Markdown horizontal rule

hud/utils/agent.py

@@ -1,37 +0,0 @@
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from hud.task import Task
-
-AGENT_PROMPT = (
-    "You are an AI agent whose goal is to accomplish the ultimate task following the instructions."
-)
-
-
-def format_agent_prompt(environment_prompt: str | None, task: Task | None) -> str:
-    """
-    Format the agent prompt with the environment prompt and the task prompt.
-    """
-    prompt = AGENT_PROMPT
-
-    # User-provided system prompt takes precedence over environment prompt
-    if task and task.system_prompt:
-        prompt += f"\n\n{task.system_prompt}"
-    elif environment_prompt:
-        prompt += f"\n\n{environment_prompt}"
-
-    if task:
-        if task.sensitive_data:
-            prompt += "\n\nHere are placeholders for sensitive data for each domain:"
-            for domain, credentials in task.sensitive_data.items():
-                prompt += f"\n{domain}: "
-                placeholders = [f"{key}" for key in credentials]
-                prompt += f"{', '.join(placeholders)}"
-            prompt += "\n\nYou can type these placeholders to enter the sensitive data when needed."
-
-        if task.prompt:
-            prompt += f"\n\n{task.prompt}"
-
-    return prompt

hud/utils/common.py

@@ -1,256 +0,0 @@
-from __future__ import annotations
-
-import io
-import logging
-import tarfile
-import zipfile
-from typing import TYPE_CHECKING, Any, TypedDict
-
-from pathspec import PathSpec
-from pydantic import BaseModel
-
-from hud.server.requests import make_request
-from hud.settings import settings
-
-if TYPE_CHECKING:
-    from collections.abc import Iterator
-    from pathlib import Path
-
-logger = logging.getLogger("hud.utils.common")
-
-
-class FunctionConfig(BaseModel):
-    function: str  # Format: "x.y.z"
-    args: list[Any]  # Must be json serializable
-
-    id: str | None = None  # Optional id for remote execution
-    metadata: dict[str, Any] | None = None  # Optional metadata for telemetry
-
-    def __len__(self) -> int:
-        return len(self.args)
-
-    def __getitem__(self, index: int) -> Any:
-        return self.args[index]
-
-    def __iter__(self) -> Iterator[Any]:
-        return iter(self.args)
-
-    def __str__(self) -> str:
-        return f"FC: {self.function}: {', '.join(str(arg) for arg in self.args)} ({self.metadata})"
-
-
-# Type alias for the shorthand config, which just converts to function name and args
-BasicType = str | int | float | bool | None
-ShorthandConfig = tuple[BasicType | dict[str, Any] | list[BasicType] | list[dict[str, Any]], ...]
-
-# Type alias for multiple config formats
-FunctionConfigs = (
-    ShorthandConfig
-    | FunctionConfig
-    | list[FunctionConfig]
-    | list[ShorthandConfig]
-    | dict[str, Any]
-    | str
-)
-
-
-class Observation(BaseModel):
-    """
-    Observation from the environment.
-
-    Attributes:
-        screenshot: Base64 encoded PNG string of the screen
-        text: Text observation, if available
-    """
-
-    screenshot: str | None = None  # base64 string png
-    text: str | None = None
-
-    def __str__(self) -> str:
-        return f"""Observation(screenshot={
-            f"{self.screenshot[:100]}..." if self.screenshot else "None"
-        }, text={f"{self.text[:100]}..." if self.text else "None"})"""
-
-
-class ExecuteResult(TypedDict):
-    """
-    Result of an execute command.
-
-    Attributes:
-        stdout: Standard output from the command
-        stderr: Standard error from the command
-        exit_code: Exit code of the command
-    """
-
-    stdout: bytes
-    stderr: bytes
-    exit_code: int
-
-
-# ---------------------------------------------------------------------------
-# Helper functions for handling ignore patterns
-# ---------------------------------------------------------------------------
-
-
-def _read_ignore_file(file_path: Path) -> list[str]:
-    """Return patterns from *file_path* (ignoring blanks / comments)."""
-    if not file_path.exists():
-        return []
-
-    patterns: list[str] = []
-    for line in file_path.read_text().splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        patterns.append(stripped)
-    return patterns
-
-
-def _gather_ignore_patterns(root_dir: Path, filename: str) -> list[str]:
-    """Collect *filename* patterns throughout *root_dir* respecting hierarchy.
-
-    For a nested ignore file located at ``sub/dir/.gitignore`` containing the
-    pattern ``foo/``, the returned pattern will be ``sub/dir/foo/`` so that it
-    is evaluated relative to *root_dir* when passed to ``PathSpec``.
-    """
-    gathered: list[str] = []
-
-    root_dir = root_dir.resolve()
-
-    for ignore_file in root_dir.rglob(filename):
-        prefix = ignore_file.parent.relative_to(root_dir).as_posix()
-        base_prefix = "" if prefix == "." else prefix
-
-        for pat in _read_ignore_file(ignore_file):
-            negate = pat.startswith("!")
-            pat_body = pat[1:] if negate else pat
-
-            # Leading slash means relative to the directory the ignore file is
-            # located in - remove it so we can prepend *prefix* below.
-            if pat_body.startswith("/"):
-                pat_body = pat_body.lstrip("/")
-
-            full_pattern = f"{base_prefix}/{pat_body}" if base_prefix else pat_body
-            if negate:
-                full_pattern = f"!{full_pattern}"
-
-            gathered.append(full_pattern)
-
-    return gathered
-
-
-def _compile_pathspec(
-    directory: Path,
-    *,
-    respect_gitignore: bool,
-    respect_dockerignore: bool,
-    respect_hudignore: bool,
-) -> PathSpec | None:
-    """Compile a ``PathSpec`` from all relevant ignore files under *directory*.
-
-    In addition to the standard ``.gitignore`` and ``.dockerignore`` files we now
-    recognise a project-specific ``.hudignore`` file that shares the same pattern
-    syntax. Each file can be toggled independently through the corresponding
-    ``respect_*`` keyword argument.
-    """
-    patterns: list[str] = []
-
-    if respect_gitignore:
-        patterns.extend(_gather_ignore_patterns(directory, ".gitignore"))
-    if respect_dockerignore:
-        patterns.extend(_gather_ignore_patterns(directory, ".dockerignore"))
-    if respect_hudignore:
-        patterns.extend(_gather_ignore_patterns(directory, ".hudignore"))
-
-    if not patterns:
-        return None
-
-    return PathSpec.from_lines("gitwildmatch", patterns)
-
-
-def _iter_files(
-    directory: Path,
-    *,
-    respect_gitignore: bool,
-    respect_dockerignore: bool,
-    respect_hudignore: bool,
-) -> Iterator[tuple[Path, Path]]:
-    """Yield ``(file_path, relative_path)`` while respecting ignore files."""
-    spec = _compile_pathspec(
-        directory,
-        respect_gitignore=respect_gitignore,
-        respect_dockerignore=respect_dockerignore,
-        respect_hudignore=respect_hudignore,
-    )
-
-    for file_path in directory.rglob("*"):
-        if not file_path.is_file():
-            continue
-        rel_path = file_path.relative_to(directory)
-        rel_str = rel_path.as_posix()
-        if spec and spec.match_file(rel_str):
-            continue
-        yield file_path, rel_path
-
-
-def directory_to_tar_bytes(
-    directory_path: Path,
-    *,
-    respect_gitignore: bool = False,
-    respect_dockerignore: bool = False,
-    respect_hudignore: bool = True,
-) -> bytes:
-    """
-    Converts a directory to a tar archive and returns it as bytes.
-
-    By default the archive respects ignore rules defined in ``.gitignore``,
-    ``.dockerignore`` and ``.hudignore`` (each can be disabled via kwargs).
-    """
-    output = io.BytesIO()
-
-    with tarfile.open(fileobj=output, mode="w") as tar:
-        for file_path, rel_path in _iter_files(
-            directory_path,
-            respect_gitignore=respect_gitignore,
-            respect_dockerignore=respect_dockerignore,
-            respect_hudignore=respect_hudignore,
-        ):
-            logger.debug("Adding %s to tar archive", rel_path)
-            tar.add(file_path, arcname=str(rel_path))
-
-    output.seek(0)
-    return output.getvalue()
-
-
-def directory_to_zip_bytes(
-    context_dir: Path,
-    *,
-    respect_gitignore: bool = False,
-    respect_dockerignore: bool = False,
-    respect_hudignore: bool = True,
-) -> bytes:
-    """Zip *context_dir* and return the zip archive as bytes, respecting ignore rules."""
-    output = io.BytesIO()
-    with zipfile.ZipFile(output, "w", zipfile.ZIP_DEFLATED) as zipf:
-        for file_path, rel_path in _iter_files(
-            context_dir,
-            respect_gitignore=respect_gitignore,
-            respect_dockerignore=respect_dockerignore,
-            respect_hudignore=respect_hudignore,
-        ):
-            logger.debug("Adding %s to zip archive", rel_path)
-            zipf.write(str(file_path), arcname=str(rel_path))
-    return output.getvalue()
-
-
-async def get_gym_id(gym_name_or_id: str) -> str:
-    """
-    Get the gym ID for a given gym name or ID.
-    """
-    data = await make_request(
-        method="GET",
-        url=f"{settings.base_url}/v1/gyms/{gym_name_or_id}",
-        api_key=settings.api_key,
-    )
-
-    return data["id"]

hud/utils/config.py

@@ -1,120 +0,0 @@
-from __future__ import annotations
-
-import logging
-import re
-from typing import TYPE_CHECKING
-
-from hud.utils.common import FunctionConfig, FunctionConfigs
-
-if TYPE_CHECKING:
-    from typing import TypeGuard
-
-logger = logging.getLogger("hud.utils.config")
-
-REMOTE_FUNCTION_PREFIX = "private_"
-REMOTE_SETUP = "setup"
-REMOTE_EVALUATE = "evaluate"
-
-LOCAL_EVALUATORS = ["response_is", "response_includes", "response_match"]
-
-
-def _is_valid_python_name(name: str) -> bool:
-    """Check if a string is a valid Python identifier."""
-    return bool(re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name))
-
-
-def _validate_hud_config(config: dict) -> FunctionConfig:
-    """Validate and convert a dictionary to an FunctionConfig."""
-    if not isinstance(config.get("function"), str):
-        raise ValueError("function must be a string")
-
-    # Validate function path components
-    _split_and_validate_path(config["function"])
-
-    args = config["args"] if isinstance(config.get("args"), list) else [config["args"]]
-
-    # Create a proper FunctionConfig object instead of using cast
-    return FunctionConfig(function=config["function"], args=args, id=config.get("id"))
-
-
-def _split_and_validate_path(path: str) -> None:
-    """Split a function path into components, validating each part."""
-    parts = path.split(".")
-
-    if not parts:
-        raise ValueError("Empty function path")
-
-    # Validate each part
-    for part in parts:
-        if not _is_valid_python_name(part):
-            raise ValueError(f"Invalid Python identifier in path: {part}")
-
-
-def _is_list_of_configs(config: FunctionConfigs) -> TypeGuard[list[FunctionConfig]]:
-    """Check if a config is a list of FunctionConfig objects."""
-    return isinstance(config, list) and all(isinstance(item, FunctionConfig) for item in config)
-
-
-def expand_config(config: FunctionConfigs) -> list[FunctionConfig]:
-    """
-    Process a config into a standardized list of FunctionConfig objects.
-
-    Args:
-        config: Can be:
-            - A tuple where first element is function name and rest are args
-            - A FunctionConfig object
-            - A dictionary with "function" and "args" keys
-            - A list of FunctionConfig objects
-
-    Returns:
-        list[FunctionConfig]: List of standardized configurations
-
-    Raises:
-        ValueError: If the configuration format is invalid
-    """
-    logger.debug("Processing config: %s", config)
-
-    # If it's already a FunctionConfig, just wrap it in a list
-    if isinstance(config, FunctionConfig):
-        return [config]
-
-    # If it's a list of FunctionConfigs, return as is
-    if _is_list_of_configs(config):
-        return config
-
-    # Handle dictionary configuration
-    if isinstance(config, dict):
-        return [_validate_hud_config(config)]
-
-    if isinstance(config, str):
-        return [FunctionConfig(function=config, args=[])]
-
-    # Handle tuple format
-    if isinstance(config, tuple):
-        if len(config) < 1 or not isinstance(config[0], str):
-            error_msg = "Invalid tuple configuration. "
-            "Expected tuple[str, ...], got: {type(config)}"
-            logger.error(error_msg)
-            raise ValueError(error_msg)
-
-        # First element is the function name, rest are args
-        function_name = config[0]
-        args = list(config[1:]) if len(config) > 1 else []
-
-        return [FunctionConfig(function=function_name, args=args)]
-
-    if isinstance(config, list):
-        result = []
-        for item in config:
-            if isinstance(item, tuple) and len(item) >= 1 and isinstance(item[0], str):
-                function_name = item[0]
-                args = list(item[1:]) if len(item) > 1 else []
-                result.append(FunctionConfig(function=function_name, args=args))
-            else:
-                raise ValueError(f"Invalid list item configuration: {item}")
-        return result
-
-    # Unknown configuration type
-    error_msg = f"Unknown configuration type: {type(config)}"
-    logger.error(error_msg)
-    raise ValueError(error_msg)