hud-python 0.1.4__py3-none-any.whl → 0.2.0__py3-none-any.whl

hud/environment.py

@@ -1,317 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import enum
-import logging
-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 BaseResponseWithLogs(BaseModel):
-    """Base model for API responses that include logs."""
-    logs: str | None = None
-    error: str | None = None
-
-
-class RewardResponse(BaseResponseWithLogs):
-    reward: float
-
-
-logger = logging.getLogger("hud.environment")
-
-
-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 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"
-
-
-status_messages = {
-    EnvironmentStatus.RUNNING.value: "is running",
-    EnvironmentStatus.ERROR.value: "had an error initializing",
-    EnvironmentStatus.COMPLETED.value: "completed",
-}
-
-
-class Environment:
-    """
-    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,
-        adapter: Adapter,
-        run_id: str,
-        id: str | None = None,
-        config: dict[str, Any] | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> None:
-        """
-        Initialize an environment.
-
-        Args:
-            adapter: Adapter for converting actions
-            run_id: ID of the run this environment belongs to
-            id: Optional ID of an existing environment
-            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
-        self.final_response: None | str = None
-        self.id = id
-        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) -> RewardResponse:
-        """
-        Get final evaluation score.
-
-        Returns:
-            RewardResponse: The evaluation response containing reward, logs, and possible error
-        """
-        data = await make_request(
-            method="POST",
-            url=f"{settings.base_url}/evaluation/{self.id}",
-            api_key=settings.api_key,
-        )
-        return RewardResponse(**data)
-
-    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"])
-
-    async def wait_for_ready(self) -> None:
-        """Wait for the environment to be ready"""
-        while True:
-            state = await self.get_env_state()
-            if state in (
-                EnvironmentStatus.RUNNING.value,
-                EnvironmentStatus.ERROR.value,
-                EnvironmentStatus.COMPLETED.value,
-            ):
-                logger.info("Environment %s %s", self.id, status_messages.get(state))
-                break
-            await asyncio.sleep(10)
-
-
-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,
-        configs: dict[str, Any] | 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 []
-        self.configs = configs 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,
-        )
-        # Extracts a list of task ids and list of config objects for the evalset
-        self.tasks = data["tasks"]
-        self.configs = data["evalset"]
-        return self.tasks

hud/run.py

@@ -1,208 +0,0 @@
-from __future__ import annotations
-
-import datetime
-from typing import TYPE_CHECKING, Any
-
-from pydantic import BaseModel, Field
-
-from .adapters.common import Adapter
-from .environment import Environment, EvalSet
-from .server import make_request
-from .settings import settings
-
-if TYPE_CHECKING:
-    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
-        config: Dictionary containing configuration parameters
-        metadata: Dictionary containing metadata
-    """
-
-    id: str
-    name: str
-    gym: dict[str, Any]
-    evalset: 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.datetime
-    raw_data: dict[str, list[dict[str, Any]]] = Field(
-        default_factory=lambda: {"tasks": [], "environments": []}
-    )
-
-    def __str__(self) -> str:
-        return self.visualize()
-
-    def visualize(self) -> str:
-        """
-        Generate an ASCII bar chart visualization of run analytics.
-
-        Args:
-            data: The run analytics data to visualize
-
-        Returns:
-            A string containing an ASCII visualization
-        """
-        max_width = 50
-
-        completion_rate = self.completion_rate if self.completion_rate is not None else 0
-
-        result = [
-            f"Run: {self.name} (ID: {self.id})",
-            f"Created: {self.created_at.strftime('%Y-%m-%d %H:%M:%S')}",
-            "-" * 60,
-            f"""Progress: {self.completed_tasks}/{self.total_tasks} tasks completed (
-            {completion_rate:.1f}% completion rate)""",
-            "",
-        ]
-
-        result.append("Status Distribution:")
-        total = sum(self.status_counts.values())
-        for status, count in self.status_counts.items():
-            percentage = (count / total) * 100
-            bar_length = int((count / total) * max_width)
-            bar = "█" * bar_length
-            result.append(f"{status.ljust(10)}: {bar} {count} ({percentage:.1f}%)")
-
-        if self.avg_score is not None:
-            result.append("")
-            result.append(f"Average Score: {self.avg_score:.2f}")
-
-            score_bar_length = int((self.avg_score / 100) * max_width)
-            score_bar = "█" * score_bar_length
-            result.append(f"Score: {score_bar} {self.avg_score:.2f}/1.00")
-
-        if self.running_time is not None:
-            hours, remainder = divmod(self.running_time, 3600)
-            minutes, seconds = divmod(remainder, 60)
-            runtime_str = f"{int(hours)}h {int(minutes)}m {int(seconds)}s"
-            result.append(f"Total Runtime: {runtime_str}")
-
-        return "\n".join(result)
-
-
-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.environments: list[Environment] = []
-
-    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] | None = None) -> Environment:
-        """
-        Create a new environment for this run.
-
-        Args:
-            metadata: Metadata for the environment
-
-        Returns:
-            Environment: The created environment
-        """
-        # Make the env class
-        env = Environment(
-            run_id=self.id,
-            config=self.config,
-            adapter=self.adapter,
-            metadata=metadata or {},
-        )
-        await env.create_environment()
-        self.environments.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_python-0.1.4.dist-info/METADATA

@@ -1,125 +0,0 @@
-Metadata-Version: 2.4
-Name: hud-python
-Version: 0.1.4
-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: dotenv; 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
-
-A Python SDK for interacting with HUD environments and evaluation benchmarks for browser use and computer use models.
-
-> **Alpha Release Notice**: This SDK is currently in early release status. The API is 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://documentation.hud.so) | [🏠 Homepage](https://hud.so)
-
-
-## Quick start
-
-[RECOMMENDED] To set get started with an agent, see the [Claude Computer use example](https://github.com/Human-Data/hud-sdk/tree/main/examples).
-
-Install the package with Python>=3.9:
-```bash
-pip install hud-python
-```
-
-Make sure to setup your account with us (email founders@hud.so) and add your API key to the environment variables:
-```bash
-HUD_API_KEY=<your-api-key>
-```
-
-Load in your agent and create a run! Go to the [examples](https://github.com/Human-Data/hud-sdk/tree/main/examples) folder for more examples.
-```python
-import asyncio
-from hud import HUDClient
-
-async def main():
-    # Initialize client with API key
-    client = HUDClient(api_key=os.getenv("HUD_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 = await client.create_run(name="example-run", gym=gym, evalset=evalset)
-    env = await run.make(metadata={"agent_id": "OSWORLD-1"})
-    await env.wait_for_ready()
-    
-    ### 
-    ### Agent loop goes here, see example in /examples
-    ###
-
-    # Evaluate the environment
-    result = await env.evaluate()
-
-    # Close the environment when done
-    await env.close()
-
-    # Get analytics for the run such as rewards, task completions, etc.
-    analytics = await run.get_analytics()
-    print(analytics)
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
-## Documentation
-
-For comprehensive guides, examples, and API reference, visit [our docs](https://docs.hud.so/introduction)
-
-## License
-
-[MIT License](LICENSE)

hud_python-0.1.4.dist-info/RECORD

@@ -1,21 +0,0 @@
-hud/__init__.py,sha256=ExaYEMWVJDjuGwkMB8SZ90HFxxevW6iIkghOiorkY4s,414
-hud/client.py,sha256=7WHXTQhVK-T9Rj4ZooADE_c1pah5Bc1DJ9ZRqUyUnuQ,5724
-hud/environment.py,sha256=9r8eK3OVqr-wpPGlhnrpuDt-z6FIp3S3oukTZ7swN3o,8899
-hud/gym.py,sha256=aanBHtlsXrJwrFax9SbXWwk_By-X8wE3M9deS-E_s4c,463
-hud/run.py,sha256=5ukjuRNLjj5fczaWxpR_5NebFbQpoy8w81eRYy309Vg,6401
-hud/settings.py,sha256=1ScSac0ta03LkckkH2gi6SyKY2M7nr15vRGugo2C_xs,1015
-hud/adapters/__init__.py,sha256=y3H7yMl7rC-rrXG2WvePdSojoNFSui02eYTH17Xd7OY,87
-hud/adapters/claude/__init__.py,sha256=i7QEF-29FLb9qxp1eYtXs-adIk_tG54tL-9g6d3xodk,100
-hud/adapters/claude/adapter.py,sha256=ekYZixANKfx-4lENlXGaomh6Ecw4SRKtLWD5quGNWdM,5782
-hud/adapters/common/__init__.py,sha256=BjdZWJVs_AKtpFrt-tNsdQRjnz7D97DFEQirJ-r0mp8,118
-hud/adapters/common/adapter.py,sha256=SCtOuRjW5Szzd45LXCaqDEaKr2lhA-nIqSEMJ9KLsKI,5799
-hud/adapters/common/types.py,sha256=Kgj0ZhiWOU6V95qxrvf-mMCvodLV_6rGBHwP1FQdMBk,4620
-hud/server/__init__.py,sha256=VPrhyyqg3inge9J7BjcmDBNJRuvkCA9ZDXS_R5Q8ZtY,129
-hud/server/requests.py,sha256=XEJkks8jJKFnbPDH32rrI9ww9MAGELAC-8Gr09vMd2s,6102
-hud/utils/__init__.py,sha256=0m8klSLnMLeIJT23ipBXfFACk4hNWPsA6ZNqZDpv6oY,99
-hud/utils/config.py,sha256=dze0BGE4q14omjj9822kL9BeiIgWQvJyuU29A2wa1SE,193
-hud/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hud_python-0.1.4.dist-info/METADATA,sha256=NxmtHt0FdUmopz24Z_tsyeUnzLevLXotHaCocf_CMP4,4785
-hud_python-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-hud_python-0.1.4.dist-info/licenses/LICENSE,sha256=IVdfcZ8xq5apYGJS5GzRLLbm9r03Aecxd03isi-3P9k,1075
-hud_python-0.1.4.dist-info/RECORD,,