hud-python 0.1.0__tar.gz

hud_python-0.1.0/.env.example

@@ -0,0 +1,2 @@
+# Required API keys
+HUD_API_KEY="your-hud-api-key-here"

hud_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} --with=".[dev]" pytest
+
+  lint-ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run ruff
+        run: |
+          uv run --with=".[dev]" ruff format .
+          uv run --with=".[dev]" ruff check .
+
+  lint-pyright:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run pyright
+        run: uv run --with=".[dev]" pyright

hud_python-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build and publish to PyPi
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          uv build
+          uv publish

hud_python-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv
+venv
+.env
+__pycache__
+*.pyc
+.pytest_cache
+dist/
+build/
+*.egg-info/
+uv.lock
+
+# Media files
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.bmp
+*.tiff
+*.ico

hud_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

hud_python-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+# Include examples in source distribution
+include examples/*.py
+include examples/README.md
+
+# Include license and documentation
+include LICENSE
+include README.md
+include .env.example
+
+# Exclude tests and development files
+exclude tests/
+exclude .github/
+exclude *.ipynb 

hud_python-0.1.0/PKG-INFO

@@ -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)

hud_python-0.1.0/README.md

@@ -0,0 +1,69 @@
+# 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)

hud_python-0.1.0/agent/base.py

@@ -0,0 +1,7 @@
+class Agent:
+    def __init__(self):
+        self.messages = []
+        self.responses = []
+
+    def predict(self):
+        raise NotImplementedError("Subclasses must implement this method")

hud_python-0.1.0/agent/claude.py

@@ -0,0 +1,141 @@
+import os
+import json
+from agent.base import Agent
+from anthropic import Anthropic
+
+
+class Claude(Agent):
+    def __init__(self):
+        super().__init__()
+        self.client = Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+        self.model = "claude-3-7-sonnet-20250219"
+        self.max_tokens = 4096
+        self.tool_version = "20250124"
+        self.thinking_budget = 1024
+        self.conversation = []  # Store the full conversation history including Claude's responses
+
+    async def predict(self, base64_image: str | None = None, input_text: str | None = None):
+        message = self._create_message(base64_image, input_text)
+
+        # Only append the message if it's not empty
+        if message:
+            self.conversation.append(message)
+
+        response = self._generate_response()
+
+        # Check if this response contains any tool_use blocks
+        for block in response.content:
+            if hasattr(block, "type") and block.type == "tool_use":
+                break
+
+        # Add Claude's response to the conversation history
+        assistant_message = {"role": "assistant", "content": response.content}
+        self.conversation.append(assistant_message)
+
+        self.responses.append(response)
+        return response
+
+    def _create_message(self, base64_image: str | None = None, input_text: str | None = None):
+        """Create appropriate message based on context and inputs"""
+
+        # Check if the previous response was from assistant and had tool_use
+        if len(self.conversation) >= 2 and self.conversation[-1]["role"] == "assistant":
+            last_assistant_message = self.conversation[-1]
+
+            # Look for tool_use blocks in the assistant's message
+            for block in last_assistant_message["content"]:
+                if hasattr(block, "type") and block.type == "tool_use":
+                    if hasattr(block, "name") and block.name == "computer" and base64_image:
+                        # Found the tool_use to respond to
+                        return {
+                            "role": "user",
+                            "content": [
+                                {
+                                    "type": "tool_result",
+                                    "tool_use_id": block.id,
+                                    "content": [
+                                        {
+                                            "type": "image",
+                                            "source": {
+                                                "type": "base64",
+                                                "media_type": "image/png",
+                                                "data": base64_image,
+                                            },
+                                        }
+                                    ],
+                                }
+                            ],
+                        }
+
+        # Regular user message
+        if input_text or base64_image:
+            content = []
+            if input_text:
+                content.append({"type": "text", "text": input_text})
+            if base64_image:
+                content.append(
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": "image/png",
+                            "data": base64_image,
+                        },
+                    }
+                )
+
+            return {"role": "user", "content": content}
+
+        return None  # Return None if no message could be created
+
+    def _generate_response(self):
+        beta_flag = (
+            "computer-use-2025-01-24"
+            if "20250124" in self.tool_version
+            else "computer-use-2024-10-22"
+        )
+
+        tools = [
+            {
+                "type": f"computer_{self.tool_version}",
+                "name": "computer",
+                "display_width_px": 1024,
+                "display_height_px": 768,
+                "display_number": 1,
+            }
+        ]
+
+        thinking = {"type": "enabled", "budget_tokens": self.thinking_budget}
+
+        try:
+            response = self.client.beta.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                messages=self.conversation,  # Use the full conversation including assistant responses
+                tools=tools,
+                betas=[beta_flag],
+                thinking=thinking,
+            )
+            return response
+        except Exception as e:
+            raise
+
+    def process_response(self, response: dict) -> tuple[bool, str | None]:
+        # Check if response contains a computer tool use
+        has_computer_tool_use = False
+        computer_action = None
+        for block in response["content"]:
+            if block.type == "tool_use" and block.name == "computer":
+                has_computer_tool_use = True
+                computer_action = block.input
+                break
+
+        if not has_computer_tool_use:
+            # No computer tool use, treat as final response
+            return True, str(response["content"][-1].text)
+
+        # If we have a computer action, adapt it to environment actions
+        if computer_action:
+            return False, computer_action
+
+        return True, None

hud_python-0.1.0/agent/response_agent.py

@@ -0,0 +1,54 @@
+import json
+import os
+import openai
+from typing import Literal, Optional
+
+ResponseType = Literal["STOP", "CONTINUE"]
+
+class ResponseAgent:
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not self.api_key:
+            raise ValueError("OpenAI API key must be provided or set as OPENAI_API_KEY environment variable")
+        
+        self.client = openai.Client(api_key=self.api_key)
+        
+        self.system_prompt = """
+        You are an assistant that helps determine the appropriate response to an agent's message.
+        
+        You will receive messages from an agent that is performing tasks for a user.
+        Your job is to analyze these messages and respond with one of the following:
+        
+        - STOP: If the agent indicates it has successfully completed a task, even if phrased as a question
+          like "I have returned to the previous website. Would you like me to do anything else?"
+        
+        - CONTINUE: If the agent is asking for clarification before proceeding with a task
+          like "I'm about to clear cookies from this website. Would you like me to proceed?"
+        
+        Respond ONLY with one of these two options.
+        """
+    
+    def determine_response(self, agent_message: str) -> ResponseType:
+        try:
+            response = self.client.chat.completions.create(
+                model="gpt-4o",
+                messages=[
+                    {"role": "system", "content": self.system_prompt},
+                    {"role": "user", "content": f"Agent message: {agent_message}\n\nWhat is the appropriate response?"}
+                ],
+                temperature=0.1,  # Low temperature for more deterministic responses
+                max_tokens=5  # We only need a short response
+            )
+            
+            response_text = response.choices[0].message.content.strip().upper()
+            
+            # Validate the response
+            if "STOP" in response_text:
+                return "STOP"
+            else:
+                return "CONTINUE"
+                
+        except Exception as e:
+            print(f"Error determining response: {e}")
+            return "CONTINUE"
+

hud_python-0.1.0/docs/api-reference/adapters.mdx

@@ -0,0 +1,161 @@
+---
+title: 'Adapters API'
+description: 'API reference for the adapter classes'
+---
+
+# Adapters API Reference
+
+## Base Adapter Class
+
+The `Adapter` class is the base class for all adapters in the HUD SDK.
+
+### Constructor
+
+```python
+Adapter() -> Adapter
+```
+
+Creates a new adapter.
+
+### Methods
+
+#### convert
+
+```python
+convert(data: Any) -> Any
+```
+
+Converts an action from the agent's format to the CLA format.
+
+**Parameters:**
+- `data` (Any): The action data to convert
+
+**Returns:**
+- `Any`: The converted action in CLA format
+
+#### adapt_list
+
+```python
+adapt_list(actions: list[Any]) -> list[Any]
+```
+
+Adapts a list of actions.
+
+**Parameters:**
+- `actions` (list[Any]): The list of actions to adapt
+
+**Returns:**
+- `list[Any]`: The adapted list of actions
+
+## Common Action Types
+
+### ClickAction
+
+Represents a mouse click action.
+
+```python
+ClickAction(point: Point, button: str = "left") -> ClickAction
+```
+
+**Parameters:**
+- `point` (Point): The point to click
+- `button` (str, optional): The mouse button to use ("left", "right", "double")
+
+### TypeAction
+
+Represents a keyboard typing action.
+
+```python
+TypeAction(text: str, enter_after: bool = False) -> TypeAction
+```
+
+**Parameters:**
+- `text` (str): The text to type
+- `enter_after` (bool, optional): Whether to press Enter after typing
+
+### ScrollAction
+
+Represents a scrolling action.
+
+```python
+ScrollAction(delta_x: int = 0, delta_y: int = 0) -> ScrollAction
+```
+
+**Parameters:**
+- `delta_x` (int, optional): The horizontal scroll amount
+- `delta_y` (int, optional): The vertical scroll amount
+
+### DragAction
+
+Represents a drag-and-drop action.
+
+```python
+DragAction(start: Point, end: Point, button: str = "left") -> DragAction
+```
+
+**Parameters:**
+- `start` (Point): The starting point
+- `end` (Point): The ending point
+- `button` (str, optional): The mouse button to use
+
+### Point
+
+Represents a point on the screen.
+
+```python
+Point(x: int, y: int) -> Point
+```
+
+**Parameters:**
+- `x` (int): The x-coordinate
+- `y` (int): The y-coordinate
+
+## Claude Adapter
+
+The `ClaudeAdapter` class is an adapter for Anthropic's Claude models.
+
+### Constructor
+
+```python
+ClaudeAdapter() -> ClaudeAdapter
+```
+
+Creates a new Claude adapter.
+
+### Methods
+
+#### convert
+
+```python
+convert(data: Any) -> Any
+```
+
+Converts a Claude action to the CLA format.
+
+**Parameters:**
+- `data` (Any): The Claude action data
+
+**Returns:**
+- `Any`: The converted action in CLA format
+
+## Usage Example
+
+```python
+from hud.adapters.common import Adapter
+from hud.adapters.common.types import ClickAction, Point
+
+# Create a custom adapter
+class MyAdapter(Adapter):
+    def convert(self, data: Any) -> Any:
+        if isinstance(data, dict) and "type" in data:
+            if data["type"] == "click":
+                return ClickAction(
+                    point=Point(x=data["x"], y=data["y"]),
+                    button=data.get("button", "left")
+                )
+        return super().convert(data)
+
+# Use the adapter
+adapter = MyAdapter()
+env = await run.make(adapter=adapter, metadata={"agent_id": "my-agent"})
+```