hud-python 0.1.0__py3-none-any.whl

hud/env.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+
+from hud.server import make_request
+from hud.settings import settings
+
+if TYPE_CHECKING:
+    from .adapters.common import Adapter
+
+
+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
+
+
+class TaskResult(BaseModel):
+    """
+    Result of a task step.
+    
+    Attributes:
+        observation: The current observation
+        reward: Reward value from the step
+        terminated: Whether the task is complete
+        info: Additional information from the environment
+    """
+    observation: Observation
+    reward: float
+    terminated: bool
+    info: dict[str, Any]
+
+
+class Env:
+    """
+    Environment interface for agent interactions.
+    
+    This class handles the environment state and interactions, including
+    creating the environment, retrieving state, and executing actions.
+    """
+
+    def __init__(
+        self,
+        run_id: str,
+        adapter: Adapter,
+        config: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Initialize an environment.
+        
+        Args:
+            run_id: ID of the run this environment belongs to
+            adapter: Adapter for converting actions
+            config: Optional configuration parameters
+            metadata: Optional metadata for the environment
+        """
+        if metadata is None:
+            metadata = {}
+        if config is None:
+            config = {}
+        self.run_id = run_id
+        self.config = config
+        self.adapter = adapter
+        self.metadata = metadata
+        # task_run_id is created when the environment is created (create_environment)
+        # or provided if env already exists.
+        self.final_response: None | str = None
+        self.id = None
+        self.vnc_url = None
+
+    async def create_environment(self) -> str:
+        """
+        Initialize the environment and return the task_run_id.
+        
+        Returns:
+            str: The environment ID
+        """
+        data = await make_request(
+            method="POST",
+            url=f"{settings.base_url}/create_environment",
+            json={"run_id": self.run_id, "metadata": self.metadata},
+            api_key=settings.api_key,
+        )
+        self.id = data["id"]
+        return self.id
+
+    async def get_vnc_url(self) -> str:
+        """
+        Get the VNC URL for the environment.
+        
+        Returns:
+            str: The VNC URL for remote viewing/control
+        """
+        data = await make_request(
+            method="GET",
+            url=f"{settings.base_url}/environment/{self.id}/vnc",
+            api_key=settings.api_key,
+        )
+        self.vnc_url = data["vm_url"]
+        return self.vnc_url
+
+    async def get_env_state(self) -> str:
+        """
+        Get the state of the environment.
+        
+        Returns:
+            str: The current state (e.g., "running", "error")
+        """
+        data = await make_request(
+            method="GET",
+            url=f"{settings.base_url}/get_env_state/{self.id}",
+            api_key=settings.api_key,
+        )
+        return data["state"]
+
+    async def step(
+        self, action: Any | None = None
+    ) -> tuple[Observation, float, bool, dict[str, Any]]:
+        """
+        Send action to environment and get result.
+        
+        Args:
+            action: The action to take, or None for no action
+            
+        Returns:
+            tuple: (observation, reward, terminated, info)
+        """
+        action_list = self.translate_action(action) if action is not None else []
+        data = await make_request(
+            method="POST",
+            url=f"{settings.base_url}/execute_step/{self.id}",
+            json=action_list,
+            api_key=settings.api_key,
+        )
+        # Convert the raw observation to the correct type
+        self.current_observation = Observation(**data["observation"])
+        data["observation"] = self.current_observation
+        # Return the result
+        task_result = TaskResult(**data)
+        return (
+            task_result.observation,
+            task_result.reward,
+            task_result.terminated,
+            task_result.info,
+        )
+
+    def translate_action(self, action: Any) -> list:
+        """
+        Translate action to the correct format.
+        
+        Args:
+            action: The action to translate
+            
+        Returns:
+            list: List of translated actions in the CLA format
+        """
+        # Get adapter and then translate action to Common Language Action
+        if isinstance(action, list):
+            return self.adapter.adapt_list(action)
+        return [self.adapter.adapt(action)]
+
+    async def evaluate(self) -> float:
+        """
+        Get final evaluation score.
+        
+        Returns:
+            float: The evaluation score
+        """
+        data = await make_request(
+            method="POST",
+            url=f"{settings.base_url}/evaluation/{self.id}",
+            api_key=settings.api_key,
+        )
+        return data["reward"]
+
+    async def close(self) -> None:
+        """
+        Close the environment.
+        """
+        await make_request(
+            method="POST",
+            url=f"{settings.base_url}/close/{self.id}",
+            api_key=settings.api_key,
+        )
+
+    async def reset(self, task_id: str, metadata: dict[str, Any] | None = None) -> Observation:
+        """
+        Reset the environment to the task.
+        
+        Args:
+            task_id: ID of the task to reset to
+            metadata: Optional metadata for the reset
+            
+        Returns:
+            Observation: Initial observation for the task
+        """
+        if metadata is None:
+            metadata = {}
+        data = await make_request(
+            method="POST",
+            url=f"{settings.base_url}/environments/{self.id}/reset",
+            json={"task_id": task_id, "metadata": metadata},
+            api_key=settings.api_key,
+        )
+        return Observation(**data["observation"])
+
+
+class EvalSet:
+    """
+    Evaluation set containing tasks for benchmarking.
+    
+    Attributes:
+        id: Unique identifier for the evalset
+        name: Human-readable name
+        tasks: List of task IDs in this evalset
+    """
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        tasks: list[str] | None = None,
+    ) -> None:
+        """
+        Initialize an evaluation set.
+        
+        Args:
+            id: Unique identifier
+            name: Human-readable name
+            tasks: Optional list of task IDs
+        """
+        self.id = id
+        self.name = name
+        self.tasks = tasks or []
+
+    async def fetch_tasks(self) -> list[str]:
+        """
+        Fetch all tasks in this evalset from the API.
+        
+        Returns:
+            list[str]: List of task IDs
+        """
+        data = await make_request(
+            method="GET",
+            url=f"{settings.base_url}/evalsets/{self.id}/tasks",
+            api_key=settings.api_key,
+        )
+        self.tasks = data["tasks"]
+        return self.tasks

hud/gym.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+
+class Gym:
+    """
+    Represents a simulation environment in the HUD system.
+    
+    Attributes:
+        id: Unique identifier for the gym
+        name: Human-readable name of the gym
+    """
+
+    def __init__(self, id: str, name: str) -> None:
+        """
+        Initialize a gym.
+        
+        Args:
+            id: Unique identifier
+            name: Human-readable name
+        """
+        self.id = id
+        self.name = name

hud/run.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, Field
+
+from .adapters.common import Adapter
+from .env import Env, EvalSet
+from .server import make_request
+from .settings import settings
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from .gym import Gym
+
+
+class RunResponse(BaseModel):
+    """
+    Response model for run data from the API.
+    
+    Attributes:
+        id: Unique identifier for the run
+        name: Human-readable name of the run
+        gym: Dictionary containing gym information
+        evalset: Dictionary containing evalset information
+        adapter: Dictionary containing adapter information
+        config: Dictionary containing configuration parameters
+        metadata: Dictionary containing metadata
+    """
+    id: str
+    name: str
+    gym: dict[str, Any]
+    evalset: dict[str, Any]
+    adapter: dict[str, Any]
+    config: dict[str, Any]
+    metadata: dict[str, Any]
+
+
+class RunAnalyticsResponse(BaseModel):
+    """
+    Model for Run analytics data.
+    
+    Attributes:
+        id: Unique identifier for the run
+        name: Human-readable name of the run
+        status_counts: Counts of tasks in different states
+        avg_score: Average score across all tasks, if available
+        completion_rate: Percentage of tasks completed
+        total_tasks: Total number of tasks in the run
+        completed_tasks: Number of completed tasks
+        running_time: Total runtime in seconds, if available
+        created_at: When the run was created
+        raw_data: Detailed data about tasks and environments
+    """
+    id: str
+    name: str
+    status_counts: dict[str, int]  # e.g. {"completed": 5, "running": 2, "error": 1}
+    avg_score: float | None = None
+    completion_rate: float | None = None  # percentage of tasks completed
+    total_tasks: int
+    completed_tasks: int
+    running_time: float | None = None  # runtime in seconds if available
+    created_at: datetime
+    raw_data: dict[str, list[dict[str, Any]]] = Field(
+        default_factory=lambda: {"tasks": [], "environments": []}
+    )
+
+
+class Run:
+    """
+    A run represents a collection of tasks and environments.
+    
+    This class provides methods to fetch task IDs, create environments,
+    and access analytics for the run.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        name: str,
+        gym: Gym,
+        evalset: EvalSet,
+        config: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        adapter: Adapter | None = None,
+    ) -> None:
+        """
+        Initialize a run.
+        
+        Args:
+            id: Unique identifier
+            name: Human-readable name
+            gym: Gym object for this run
+            evalset: EvalSet object containing tasks
+            config: Optional configuration parameters
+            metadata: Optional metadata
+            adapter: Optional adapter for action conversion
+        """
+        adapter = adapter or Adapter()
+        if metadata is None:
+            metadata = {}
+        if config is None:
+            config = {}
+        self.id = id
+        self.name = name
+        self.gym = gym
+        self.evalset = evalset
+        self.adapter = adapter
+        self.config = config
+        self.metadata = metadata
+        self.envs: list[Env] = []
+
+    async def fetch_task_ids(self) -> list[str]:
+        """
+        Fetch task IDs for this run from the evalset.
+        
+        Returns:
+            list[str]: List of task IDs
+        """
+        return await self.evalset.fetch_tasks()
+
+    async def make(self, metadata: dict[str, Any]) -> Env:
+        """
+        Create a new environment for this run.
+        
+        Args:
+            metadata: Metadata for the environment
+            
+        Returns:
+            Env: The created environment
+        """
+        # Make the env class
+        env = Env(
+            run_id=self.id,
+            config=self.config,
+            adapter=self.adapter,
+            metadata=metadata,
+        )
+        await env.create_environment()
+        self.envs.append(env)
+        return env
+
+    async def get_analytics(self) -> RunAnalyticsResponse:
+        """
+        Get analytics for this run.
+        
+        Returns:
+            RunAnalyticsResponse: Analytics data including status counts,
+                                average score, and other metrics
+        """
+        data = await make_request(
+            method="GET",
+            url=f"{settings.base_url}/runs/{self.id}/analytics",
+            api_key=settings.api_key,
+        )
+        return RunAnalyticsResponse(**data)

hud/server/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .requests import RequestError, make_request, make_sync_request
+
+__all__ = ["RequestError", "make_request", "make_sync_request"]

hud/server/requests.py

@@ -0,0 +1,79 @@
+"""
+HTTP request utilities for the HUD API.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class RequestError(Exception):
+    """
+    Custom exception for API request errors.
+    """
+
+
+async def make_request(
+    method: str, url: str, json: Any | None = None, api_key: str | None = None
+) -> dict[str, Any]:
+    """
+    Make an asynchronous HTTP request to the HUD API.
+    
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        url: Full URL for the request
+        json: Optional JSON serializable data
+        api_key: API key for authentication
+        
+    Returns:
+        dict: JSON response from the server
+        
+    Raises:
+        RequestError: If API key is missing or request fails
+    """
+    if not api_key:
+        raise RequestError("API key is required but not provided")
+
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    async with httpx.AsyncClient(timeout=240.0) as client:
+        try:
+            response = await client.request(method=method, url=url, json=json, headers=headers)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            raise RequestError(f"Request failed: {e!s}") from None
+
+
+def make_sync_request(
+    method: str, url: str, json: Any | None = None, api_key: str | None = None
+) -> dict[str, Any]:
+    """
+    Make a synchronous HTTP request to the HUD API.
+    
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        url: Full URL for the request
+        json: Optional JSON serializable data
+        api_key: API key for authentication
+        
+    Returns:
+        dict: JSON response from the server
+        
+    Raises:
+        RequestError: If API key is missing or request fails
+    """
+    if not api_key:
+        raise RequestError("API key is required but not provided")
+
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    with httpx.Client(timeout=240.0) as client:
+        try:
+            response = client.request(method=method, url=url, json=json, headers=headers)
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPError as e:
+            raise RequestError(f"Request failed: {e!s}") from None

hud/settings.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """
+    Global settings for the HUD SDK.
+    
+    This class manages configuration values loaded from environment variables
+    and provides global access to settings throughout the application.
+    """
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="allow"
+    )
+
+    base_url: str = Field(
+        default="https://orchestrator.hud.live/hud-gym/api/v1",
+        description="Base URL for the HUD API",
+        validation_alias="base_url"
+    )
+
+    api_key: str | None = Field(
+        default=None,
+        description="API key for authentication with the HUD API",
+        validation_alias="HUD_API_KEY"
+    )
+
+
+# Create a singleton instance
+settings = Settings()
+
+# Add utility functions for backwards compatibility
+def get_settings() -> Settings:
+    """Get the global settings instance."""
+    return settings

hud/utils/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .config import configuration
+
+__all__ = ["configuration"]

hud/utils/config.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from hud.settings import settings
+
+# For backwards compatibility, keep 'configuration'
+# but have it point to the settings instance
+configuration = settings

hud_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: hud-python
+Version: 0.1.0
+Summary: SDK for the HUD evaluation platform.
+Project-URL: Homepage, https://github.com/Human-Data/hud-sdk
+Project-URL: Bug Tracker, https://github.com/Human-Data/hud-sdk/issues
+Project-URL: Documentation, https://hud.so
+Author-email: Human Union Data SDK <founders@hud.so>
+License: MIT License
+        
+        Copyright (c) 2025 Human Data Company
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.9
+Requires-Dist: eval-type-backport>=0.2.2
+Requires-Dist: httpx<1,>=0.23.0
+Requires-Dist: pillow<12,>=11
+Requires-Dist: pydantic-settings<3,>=2
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: anthropic; extra == 'dev'
+Requires-Dist: ipykernel; extra == 'dev'
+Requires-Dist: ipython<9; extra == 'dev'
+Requires-Dist: jupyter-client; extra == 'dev'
+Requires-Dist: jupyter-core; extra == 'dev'
+Requires-Dist: openai; extra == 'dev'
+Requires-Dist: pyright==1.1.364; extra == 'dev'
+Requires-Dist: pytest<9,>=8.1.1; extra == 'dev'
+Requires-Dist: ruff==0.9.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HUD SDK (Alpha Release)
+
+A Python SDK for interacting with HUD environments and evaluation benchmarks for browser use and computer use models.
+
+Visit [hud.so](https://hud.so) for more information about HUD.
+
+> **Alpha Release Notice**: This SDK is currently in alpha status (v0.1.0-alpha). The API is still evolving and may change in future releases as we gather feedback and improve functionality.
+
+[![PyPI version](https://img.shields.io/pypi/v/hud-python)](https://pypi.org/project/hud-python/)
+
+[📚 Documentation](https://docs.hud.so) | [🏠 Homepage](https://hud.so)
+
+## Quick Start
+
+```bash
+# Install the latest stable release
+pip install hud-python
+
+# Install the latest alpha release (may include breaking changes)
+pip install --pre hud-python
+
+# Install a specific alpha version
+pip install hud-python==0.1.0-alpha
+```
+
+```python
+import asyncio
+from hud import HUDClient
+
+async def main():
+    # Initialize client with API key
+    client = HUDClient(api_key="your-api-key")
+    
+    # Load a gym and evaluation set
+    gym = await client.load_gym(id="OSWorld-Ubuntu")
+    evalset = await client.load_evalset(id="OSWorld-Ubuntu")
+    
+    # Create a run and environment
+    run = client.create_run(name="example-run", gym=gym, evalset=evalset)
+    env = await run.make(metadata={"agent_id": "example"})
+
+    # Agent loop goes here
+    # For complete examples and usage guides, see our documentation
+
+    # Close the environment when done
+    await env.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Key Features
+
+- Connect to HUD evaluation environments
+- Run benchmarks across various tasks
+- Support for different agent adapters
+- Asynchronous API for efficient interaction
+
+## Documentation
+
+For comprehensive guides, examples, and API reference, visit:
+- [Getting Started](https://docs.hud.so/introduction)
+- [Installation](https://docs.hud.so/installation)
+- [API Reference](https://docs.hud.so/api-reference)
+- [Examples](https://docs.hud.so/examples)
+
+## License
+
+[MIT License](LICENSE)