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

hud_python-0.2.0.dist-info/METADATA

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: hud-python
+Version: 0.2.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 Union Data, Inc
+        
+        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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.10
+Requires-Dist: aiodocker>=0.24.0
+Requires-Dist: httpx<1,>=0.23.0
+Requires-Dist: inspect-ai>=0.3.80
+Requires-Dist: pillow>=11.1.0
+Requires-Dist: pydantic-settings<3,>=2
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: textdistance<5,>=4.5.0
+Requires-Dist: toml>=0.10.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 SDK - Human-Agent Interaction Toolkit
+
+A Python SDK for creating, evaluating, and benchmarking agent interactions with web browsers and OS environments.
+
+> **Early 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)
+
+## API Key Setup
+
+Before getting started, you'll need to obtain an API key:
+
+1. Visit [app.hud.so](https://app.hud.so) to create a free account and generate your API key
+2. Set it in your environment or .env file:
+
+```bash
+export HUD_API_KEY=your_api_key_here
+```
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install hud-python
+```
+
+### Simple Browser Example with Operator
+
+> This example uses the `@job("test-run")` decorator, so the results of this run will appear under the job named "test-run" on the your [HUD Jobs page](https://app.hud.so/jobs).
+
+```python
+import os
+import asyncio
+from hud import gym, job
+from hud.task import Task
+from hud.utils import stream
+from hud.agent import OperatorAgent
+
+@job("test-run")
+async def main():
+    # Define a simple task
+    task = Task(
+        prompt="Insert the text 'capybara' into the search bar",
+        gym="hud-browser",
+        setup=("goto", "google.com"),
+        evaluate=("contains_text", "capybara")
+    )
+    
+    # Create environment
+    env = await gym.make(task)
+    
+    # Get URLs and display live view (optional)
+    # urls = await env.get_urls()
+    # stream(urls["live_url"])
+    
+    # Initialize Operator agent (API key is loaded automatically)
+    agent = OperatorAgent()
+    
+    # Agent loop
+    obs, _ = env.reset()
+    for i in range(5):
+        actions, done = await agent.predict(obs)
+        if done:
+            break
+        
+        obs, reward, terminated, info = await env.step(actions)
+        if terminated:
+            break
+    
+    # Evaluate and close
+    result = await env.evaluate()
+    print(f"Evaluation result: {result}")
+    await env.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+```
+
+## Documentation Sections
+
+Explore the core concepts and features of the SDK:
+
+*   **[Tasks and TaskSets](/concepts/task)**: Define goals, context, setup, and evaluation criteria for agent scenarios.
+*   **[Environments](/concepts/environment)**: Understand the browser and OS runtimes where agents interact.
+*   **[Agents](/concepts/agent)**: Learn about the agent architecture (Claude, Operator) and how they process observations and predict actions.
+*   **[Adapters](/concepts/adapter)**: See how actions and observations are translated between agents and environments.
+*   **[Jobs](/concepts/job)**: Group related runs for analysis and viewing on the HUD platform.
+*   **[Trajectories](/concepts/trajectory)**: Understand the recorded data from each agent run.
+*   **Advanced Topics**:
+    *   **[Custom Environments](/advanced/custom-environments)**: Build your own Docker-based local or remote environments.
+    *   **[Advanced Environment Control](/advanced/environment-control)**: Use `invoke`, `execute`, and `_setup` for finer control.
+    *   **[CLA Action Details](/advanced/cla-details)**: Dive deeper into the standardized action format.
+
+*   **[Full API Reference](/api-reference/gym)**: Detailed specifications for all modules and classes.
+
+## [Examples](examples/)
+
+We provide several example notebooks showing how to use the HUD SDK:
+
+1. [Browser Basics](examples/browser_use.ipynb) - Simple browser interaction with live view
+2. [Task Design](examples/tasks.ipynb) - Creating and customizing tasks
+3. [OSWorld](examples/osworld.ipynb) - Working with OS environments
+4. [Local Development](examples/local.ipynb) - Setting up local custom environments
+
+## Documentation
+
+For comprehensive guides, examples, and API reference, visit [our docs](https://docs.hud.so/introduction)
+
+## License
+
+[MIT License](LICENSE)
+
+## Citation
+
+If you use this SDK in your research, please cite it as follows:
+
+```bibtex
+@software{hud2025agentevalplatform,
+  author = {HUD and Jay Ram and Lorenss Martinsons and Parth Patel and Max Muoto and Oskars Putans and Govind Pimpale and Mayank Singamreddy and Nguyen Nhat Minh},
+  title = {{HUD: An Evaluation Platform for Computer Use Agents}},
+  date = {2025-03},
+  url = {https://github.com/Human-Data/hud-sdk},
+  langid = {en}
+}
+```

hud_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+hud/__init__.py,sha256=YX9zAqOSjAFZqHbDJGUVefOsxg7PhkH1ZDflRoiSgP8,464
+hud/gym.py,sha256=cKjIuJS7A0vJx4K7fctpUjIEv8TkW5x6aB_PRrODrDY,3651
+hud/job.py,sha256=E4RN1CkppRQVy46RWCUDjNIyhMa7lNlFfCgpky2vKFk,5463
+hud/settings.py,sha256=rv8TiZx4wmBzIoEEkOzoywC0nt8UZXlHxIa_LW4tWAg,1346
+hud/task.py,sha256=q1E_urMavnfsb87x2JHkRNMBzbkkaQI1skOulkpJ5DY,5132
+hud/taskset.py,sha256=fV4QgHf8tphDoMjTdBzkyCJT7pQBLEMoGu_Uxuji2DM,2226
+hud/trajectory.py,sha256=PA-sE2iyt2BctO2Dex-2ZaRmS95AkEXTicZjHCVCYqE,3749
+hud/types.py,sha256=fJZnzK3j3mq7G0gO5TbqRaN92qT4xAb4jUNOXIX8ZZ0,2395
+hud/adapters/__init__.py,sha256=0RNQgrzBCkhNBq1Q7JRESN1WfUVLs_99fR5g1re3APs,207
+hud/adapters/claude/__init__.py,sha256=i7QEF-29FLb9qxp1eYtXs-adIk_tG54tL-9g6d3xodk,100
+hud/adapters/claude/adapter.py,sha256=sgdgkCtNFjFPSSmfsUD1vx0Xz9xhG81A_it4BvRsOXE,5781
+hud/adapters/common/__init__.py,sha256=BjdZWJVs_AKtpFrt-tNsdQRjnz7D97DFEQirJ-r0mp8,118
+hud/adapters/common/adapter.py,sha256=ls-gXtg1N_SQc211rkDb3LL511HNZv6etm1nx2ZtrkQ,5808
+hud/adapters/common/types.py,sha256=ubnWlm4JMtCkTNonKZGb425p6oi8jZyIVcekp-pjTXQ,4905
+hud/adapters/operator/__init__.py,sha256=31vTRs268_TOLd-TeQRKau5bDYy78wxCNpJFhD5_l8U,104
+hud/adapters/operator/adapter.py,sha256=j2bBe_bwOhdbd7Qr6UvWUEkTkUTOA-ADvWYx0B1c_TU,3159
+hud/agent/__init__.py,sha256=cI3bqfmG2_Lwzn2RjrxV0X9qIxCRDiffwd1UaWToct4,238
+hud/agent/base.py,sha256=RThJ_h4A3oU23zyvvKtxY2a_YM03Vd1XYDXdY3bAf8g,3881
+hud/agent/claude.py,sha256=ZPoged_sun2CmPgludfkV4uv-gjak_yyIlGgCIRcWx0,6583
+hud/agent/operator.py,sha256=zJaYW5kJ7rgvRQCufrjsoNCPn2Ra9EakmFFwut_v7Hk,7335
+hud/env/__init__.py,sha256=BHFY_N0kEI142pjWtMyqUb3BGnoiekY8evRCIbSbO2w,271
+hud/env/client.py,sha256=SPR6ct6NFxmIrgIi3K8tEC-vnqOmCbCBtuT81PaVjuY,869
+hud/env/docker_client.py,sha256=4G3OeFBCbIqg9zOXxreDekNvLNMhgtc2cMAjMbqB6Tk,10394
+hud/env/environment.py,sha256=h-Z7I_1Y8vXBL1oOYbC5xRIKwl28NZt0PJ4GmKcd0AM,5863
+hud/env/local_docker_client.py,sha256=9p2IHeSRmk9_lU7FRiHaCMWn0CjbtWLQjsT3x8x6qxY,7767
+hud/env/remote_client.py,sha256=iJiwueuf98xOx0_Y2ltu_63BwKIKNvohhim73Goq74E,5804
+hud/env/remote_docker_client.py,sha256=FwaO7NyygDt9oe3pDD7PwUS21pxzc465mwcXk-Cx-60,6838
+hud/evaluators/__init__.py,sha256=XophB666xPnurhQ_ygfW44h0Jh0BQGCgUzCXEOG2Q1g,158
+hud/evaluators/base.py,sha256=CNbrvFWQfl1YuBxJKzuG4_TBAdAf0TOQA3hl7eGsbaA,782
+hud/evaluators/inspect.py,sha256=eTu9E2eBFe4jd4sPtXL0_vGIEY8aiEmTgmN__v77jvI,735
+hud/evaluators/judge.py,sha256=0T9DHFRR38oH2X1d87t58SBSAhbKWRH5PlljzCa3rkg,6449
+hud/evaluators/match.py,sha256=iFJ_qqaHJQ19TICdQPjHgTubBhq7izCIET5qU_104Fk,4719
+hud/evaluators/remote.py,sha256=NVUJJvrpGQj2eL-aFxzTEnAWW7iuSI9eDWtar54dc6E,2174
+hud/server/__init__.py,sha256=cxDKTwMdGzhj7bYajtejN8XCt7K8Xq3eKB2No0qBpoY,169
+hud/server/requests.py,sha256=s8LZZYWT1wl7lPu2vwRaYPZs9_gjKwSg3LZLvS5-s6E,9085
+hud/utils/__init__.py,sha256=LnoI2tQUnd-mQ4eg-gpJJgmHBBIhggJ6c9ap7MBgrfs,260
+hud/utils/common.py,sha256=qTAgiqQqplfrCrll06SAYYr9TyT8gnV4mwDSxsj-W1s,1842
+hud/utils/config.py,sha256=x3F9Rg2lTGEG8_FcnEyymh4Y02qD1UWmcDlOSA1Xq0U,6476
+hud/utils/telemetry.py,sha256=md7AuKxtDqsONMeeTOHen1XpmNds8CbXROX_PnkDxFc,1993
+hud/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hud_python-0.2.0.dist-info/METADATA,sha256=GbG7OHnQ8WqR3iXT6utC26PkCmgPKrOePTdCNZxuwK4,7222
+hud_python-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hud_python-0.2.0.dist-info/licenses/LICENSE,sha256=yIzBheVUf86FC1bztAcr7RYWWNxyd3B-UJQ3uddg1HA,1078
+hud_python-0.2.0.dist-info/RECORD,,

{hud_python-0.1.5.dist-info → hud_python-0.2.0.dist-info}/licenses/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Human Data Company
+Copyright (c) 2025 Human Union Data, Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

hud/client.py

@@ -1,200 +0,0 @@
-"""
-HUD client for interacting with the API.
-"""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-from .adapters.common import Adapter
-from .environment import EvalSet
-from .gym import Gym
-from .run import Run, RunResponse
-from .server import make_request
-from .settings import settings
-
-
-class HUDClient:
-    """
-    Client for interacting with the HUD API.
-
-    This is the main entry point for the SDK, providing methods to load gyms,
-    evalsets, and create runs.
-    """
-
-    def __init__(self, api_key: str | None = None) -> None:
-        """
-        Initialize the HUD client with an API key.
-
-        Args:
-            api_key: API key for authentication with the HUD API
-        """
-        self.api_key = api_key or settings.api_key
-        settings.api_key = self.api_key
-
-    async def load_gym(self, id: str) -> Gym:
-        """
-        Load a gym by ID from the HUD API.
-
-        Args:
-            id: The ID of the gym to load
-
-        Returns:
-            Gym: The loaded gym object
-        """
-        # API call to get gym info
-        data = await make_request(
-            method="GET",
-            url=f"{settings.base_url}/gyms/{id}",
-            api_key=self.api_key,
-        )
-        return Gym(id=data["id"], name=data["name"])
-
-    async def load_evalset(self, id: str) -> EvalSet:
-        """
-        Load an evalset by ID from the HUD API.
-
-        Args:
-            id: The ID of the evalset to load
-
-        Returns:
-            EvalSet: The loaded evalset object
-        """
-        # API call to get evalset info
-        data = await make_request(
-            method="GET",
-            url=f"{settings.base_url}/evalsets/{id}",
-            api_key=self.api_key,
-        )
-        return EvalSet(id=data["id"], name=data["name"])
-
-    async def list_gyms(self) -> list[str]:
-        """
-        List all available gyms.
-
-        Returns:
-            list[str]: List of gym IDs
-        """
-        # API call to get gyms
-        data = await make_request(
-            method="GET", url=f"{settings.base_url}/gyms", api_key=self.api_key
-        )
-        return data["gyms"]
-
-    async def get_runs(self) -> list[Run]:
-        """
-        Get all runs associated with the API key.
-
-        Returns:
-            list[Run]: List of run objects
-        """
-        # API call to get runs
-        data = await make_request(
-            method="GET", url=f"{settings.base_url}/runs", api_key=self.api_key
-        )
-        return data["runs"]
-
-    async def load_run(self, id: str, adapter: Adapter | None = None) -> Run | None:
-        """
-        Load a run by ID from the HUD API.
-
-        Args:
-            id: The ID of the run to load
-            adapter: Optional adapter for action conversion
-
-        Returns:
-            Run: The loaded run object, or None if not found
-        """
-        adapter = adapter or Adapter()
-        # API call to get run info
-        data = await make_request(
-            method="GET",
-            url=f"{settings.base_url}/runs/{id}",
-            api_key=self.api_key,
-        )
-        if data:
-            response = RunResponse(**data)
-            gym = Gym(id=response.gym["id"], name=response.gym["name"])
-            evalset = EvalSet(
-                id=response.evalset["id"],
-                name=response.evalset["name"],
-                tasks=response.evalset["tasks"],
-            )
-            return Run(
-                id=response.id,
-                name=response.name,
-                gym=gym,
-                evalset=evalset,
-                adapter=adapter,
-                config=response.config,
-                metadata=response.metadata,
-            )
-        return None
-
-    async def create_run(
-        self,
-        name: str,
-        gym: Gym,
-        evalset: EvalSet,
-        config: dict[str, Any] | None = None,
-        metadata: dict[str, Any] | None = None,
-        adapter: Adapter | None = None,
-    ) -> Run:
-        """
-        Create a new run in the HUD system.
-
-        Args:
-            name: Name of the run
-            gym: Gym to use for the run
-            evalset: Evalset to use for the run
-            config: Optional configuration parameters
-            metadata: Optional metadata for the run
-            adapter: Optional adapter for action conversion
-
-        Returns:
-            Run: The created run object
-        """
-        adapter = adapter or Adapter()
-        # Make synchronous API call to create run
-        if metadata is None:
-            metadata = {}
-        if config is None:
-            config = {}
-        data = await make_request(
-            method="POST",
-            url=f"{settings.base_url}/runs",
-            json={
-                "name": name,
-                "gym_id": gym.id,
-                "evalset_id": evalset.id,
-                "config": json.dumps(config),
-                "metadata": json.dumps(metadata),
-            },
-            api_key=self.api_key,
-        )
-        return Run(
-            id=data["id"],
-            name=name,
-            gym=gym,
-            evalset=evalset,
-            adapter=adapter,
-            config=config,
-            metadata=metadata,
-        )
-
-    def display_stream(self, live_url: str) -> None:
-        """
-        Display a stream in the HUD system.
-        """
-        from IPython.display import HTML, display
-
-        html_content = f"""
-        <div style="width: 960px; height: 540px; overflow: hidden;">
-            <div style="transform: scale(0.5); transform-origin: top left;">
-                <iframe src="{live_url}" width="1920" height="1080" style="border: 1px solid #ddd;">
-                </iframe>
-            </div>
-        </div>
-        """
-        display(HTML(html_content))