hud-python 0.1.4__tar.gz → 0.2.0__tar.gz

{hud_python-0.1.4 → hud_python-0.2.0}/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - name: Check out code

{hud_python-0.1.4 → hud_python-0.2.0}/.gitignore

@@ -1,4 +1,5 @@
 .venv
+.vscode
 venv
 .env
 __pycache__
@@ -10,7 +11,6 @@ build/
 uv.lock
 
 # Media files
-*.png
 *.jpg
 *.jpeg
 *.gif

{hud_python-0.1.4 → hud_python-0.2.0}/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_python-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,129 @@
+# 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/docs/advanced/cla-details.mdx

@@ -0,0 +1,92 @@
+---
+title: 'CLA Action Details'
+description: 'Detailed look at the Common Language Action (CLA) format'
+---
+
+# Common Language Action (CLA) Details
+
+The HUD SDK uses a standardized format called **CLA** (Common Language Actions) for representing agent interactions within an [Environment](/concepts/environment). When your [Agent](/concepts/agent) decides on an action (e.g., "click at x=100, y=200"), its associated [Adapter](/concepts/adapter) converts this into a specific `CLA` Pydantic model instance before it's sent to `env.step()`.
+
+Understanding the structure of these `CLA` types can be helpful for debugging or creating custom adapters/controllers. The main types are defined in `hud.adapters.common.types`.
+
+## Base Structure
+
+All CLA actions inherit from `CLAAction` and have a `type` field which acts as a discriminator:
+
+```python
+class CLAAction(pydantic.BaseModel):
+    type: str
+```
+
+## Action Categories & Examples
+
+Here are some key CLA types grouped by category:
+
+### Mouse Actions
+
+*   **`ClickAction`**: Simulates mouse clicks.
+    *   `point: Point | None`: Target coordinates (`Point(x: int, y: int)`).
+    *   `button: Literal[...]`: `"left"`, `"right"`, `"wheel"`, `"back"`, `"forward"` (default: `"left"`).
+    *   `pattern: list[int] | None`: List of delays (ms) for multi-clicks (e.g., `[100]` for double-click, `[100, 100]` for triple).
+    *   `hold_keys: list[CLAKey] | None`: Modifier keys (e.g., `"shift"`, `"ctrl"`) to hold during the click.
+    *   `selector: str | None`: Optional CSS selector to target instead of coordinates.
+
+*   **`MoveAction`**: Moves the mouse cursor.
+    *   `point: Point | None`: Target coordinates.
+    *   `selector: str | None`: Optional CSS selector to move to.
+    *   `offset: Point | None`: Offset relative to the target point/selector.
+
+*   **`ScrollAction`**: Scrolls the view.
+    *   `point: Point | None`: Coordinates *where* the scroll should originate (often ignored, scrolls the window).
+    *   `scroll: Point | None`: Scroll amount `Point(x=dx, y=dy)`. Positive `dy` scrolls down, positive `dx` scrolls right.
+    *   `hold_keys: list[CLAKey] | None`: Modifier keys to hold.
+
+*   **`DragAction`**: Simulates clicking and dragging.
+    *   `path: list[Point]`: A sequence of points defining the drag path (must have at least two points).
+    *   `pattern: list[int] | None`: Optional delays between path segments.
+    *   `hold_keys: list[CLAKey] | None`: Modifier keys to hold.
+
+### Keyboard Actions
+
+*   **`TypeAction`**: Types text.
+    *   `text: str`: The text string to type.
+    *   `selector: str | None`: Optional CSS selector to focus before typing.
+    *   `enter_after: bool | None`: Whether to press Enter after typing (default: `False`).
+
+*   **`PressAction`**: Presses and releases one or more keys simultaneously (hotkey).
+    *   `keys: list[CLAKey]`: List of key names (`CLAKey` Literal type) to press together (e.g., `["ctrl", "c"]`).
+
+*   **`KeyDownAction` / `KeyUpAction`**: Presses or releases keys without the corresponding up/down action. Useful for holding modifier keys.
+    *   `keys: list[CLAKey]`: List of key names to press down or release up.
+
+### Control Actions
+
+*   **`WaitAction`**: Pauses execution.
+    *   `time: int`: Duration to wait in milliseconds.
+
+### Fetch Actions (Get Information)
+
+*   **`ScreenshotFetch`**: Requests a screenshot (used internally, typically not sent by agents directly).
+*   **`PositionFetch`**: Requests the current cursor position (used internally).
+
+### Custom Actions
+
+*   **`CustomAction`**: Allows defining arbitrary actions specific to a custom environment controller.
+    *   `action: str`: The name/identifier of the custom action.
+    *   *(Implicit)*: Any additional fields required by the custom action can be added if defined in the custom controller logic receiving it.
+
+## `CLAKey` Type
+
+The `CLAKey` is a `typing.Literal` containing dozens of standard key names, including:
+
+*   Control Keys: `"backspace"`, `"tab"`, `"enter"`, `"shift"`, `"ctrl"`, `"alt"`, `"escape"`, `"space"`, `"pageup"`, `"pagedown"`, `"end"`, `"home"`, `"left"`, `"up"`, `"right"`, `"down"`, `"insert"`, `"delete"`.
+*   Function Keys: `"f1"`, `"f2"`, ..., `"f24"`.
+*   Numpad Keys: `"num0"`, `"num1"`, ..., `"add"`, `"multiply"`, etc.
+*   Modifier Keys: `"win"`, `"command"`, `"option"`.
+*   Printable Characters: `"a"`, `"b"`, `"1"`, `"!"`, `"#"` etc. (Note: For typing sentences, use `TypeAction`).
+
+Refer to `hud/adapters/common/types.py` for the exhaustive list.
+
+## Usage Context
+
+Remember, an [Agent](/concepts/agent) typically outputs actions in its model's native format. The [Adapter](/concepts/adapter) converts these raw actions into one or more of these specific `CLA` Pydantic model instances, which are then passed in a list to `env.step()`. 

hud_python-0.2.0/docs/advanced/custom-environments.mdx

@@ -0,0 +1,96 @@
+---
+title: 'Custom Environments'
+description: 'Define and run your own Docker-based environments locally or remotely'
+---
+
+# Custom Environments
+
+While the HUD SDK provides standard environments like `"hud-browser"` and `"OSWorld-Ubuntu"`, you can also define and run your own custom environments using Docker. This allows you to create specific testing scenarios with custom software stacks or configurations.
+
+Custom environments are defined using the `CustomGym` type from `hud.types`.
+
+## Defining a Custom Environment (`CustomGym`)
+
+```python
+from hud.types import CustomGym
+from pathlib import Path
+
+# Example 1: Local Docker environment using a source directory
+# Points to a directory containing controller code and a Dockerfile
+local_env_spec = CustomGym(
+    location="local",
+    controller_source_dir="./my_custom_controller" # Path to your controller code
+)
+
+# Example 2: Remote Docker environment (built and run on HUD platform)
+remote_env_spec = CustomGym(
+    location="remote",
+    # Dockerfile content is sent to HUD to build the image remotely
+    dockerfile="FROM ubuntu:latest\nRUN apt-get update && apt-get install -y my-package\n..."
+)
+```
+
+**Key `CustomGym` Attributes:**
+
+*   **`location` (`"local"` | `"remote"`):**
+    *   `"local"`: Builds and runs the Docker container on your *local* machine. Requires Docker installed. Ideal for development. See [Local Environment Structure](#local-environment-structure) below.
+    *   `"remote"`: Sends the `dockerfile` content to the HUD platform for remote build and execution. Good for sharing or running complex setups.
+*   **`dockerfile` (str | None):** The Dockerfile content.
+    *   Required if `location="remote"`.
+    *   Optional if `location="local"` and `controller_source_dir` is provided (will look for `Dockerfile` inside that directory).
+*   **`controller_source_dir` (str | `Path` | None):**
+    *   *Only relevant for `location="local"`.*
+    *   Path to your local directory containing the controller code and potentially the `Dockerfile`. This directory is mounted into the container.
+
+## <a name="local-environment-structure"></a>Local Environment Structure
+
+When creating a `local` custom environment, the directory specified by `controller_source_dir` typically contains:
+
+1.  **`Dockerfile`:** Defines the base image, system dependencies, Python dependencies (often via `pip install -e .`), and the command to run your controller script (`CMD [...]`).
+2.  **`pyproject.toml`:** Defines your controller as an installable Python package. The HUD SDK reads the `[project.name]` from this file to know how to import your controller code within the container after installation.
+3.  **`src/` (or your package name):** A directory containing your Python controller code. This code needs to implement the functions called by `setup`, `evaluate`, and `step` (e.g., interacting with applications inside the container, returning observations).
+
+**Example Structure (`./my_custom_controller/`):**
+
+```
+my_custom_controller/
+├── Dockerfile
+├── pyproject.toml
+└── src/
+    └── my_controller_pkg/
+        ├── __init__.py
+        └── main.py        # Your controller logic (e.g., setup, step functions)
+```
+
+*   **Examples:** The top-level `environments/` directory in the SDK repository contains reference implementations (like `novnc_ubuntu`) following this structure.
+*   **Dependencies:** For local custom environments, you might need to install development dependencies using `pip install -e ".[dev]"` in your SDK checkout to ensure the local components (like the Docker client) function correctly.
+
+## Using a Custom Environment
+
+Use your `CustomGym` object with `hud.gym.make()`:
+
+```python
+from hud import gym
+from hud.types import CustomGym
+
+# Assuming local_env_spec = CustomGym(location="local", controller_source_dir="./my_custom_controller")
+env = await gym.make(local_env_spec)
+
+print("Custom local environment created.")
+
+# Interact as usual - Task setup/evaluate calls functions in your controller
+# task = Task(prompt="...", gym=local_env_spec, setup=("my_setup_func", arg1), ...)
+# env = await gym.make(task)
+# obs, _ = await env.reset()
+# result = await env.evaluate()
+
+await env.close()
+```
+
+Creating a custom environment requires careful design of both the Dockerfile and the controller script to ensure they work together correctly.
+
+## Related Concepts
+
+*   [Environment](/concepts/environment): The runtime instance created from the `CustomGym` spec.
+*   [Task](/concepts/task): Can specify a `CustomGym` object in its `gym` attribute to request your custom environment.
+*   [Advanced Environment Control](/advanced/environment-control): Using `invoke` and `execute` for debugging or advanced control. 

hud_python-0.2.0/docs/advanced/environment-control.mdx

@@ -0,0 +1,100 @@
+---
+title: 'Advanced Environment Control'
+description: 'Using invoke, execute, and _setup for finer control over environments'
+---
+
+# Advanced Environment Control
+
+While the standard `step`, `evaluate`, and `close` methods cover most interactions, the `Environment` object provides lower-level methods for more direct control, particularly useful for custom environments, debugging, and complex setup/evaluation scenarios.
+
+## `invoke`
+
+The `env._invoke_all()` method (and its underlying `client.invoke()`) is the core mechanism for calling specific functions *within* the environment's controller script.
+
+```python
+async def _invoke_all(self, configs: HudStyleConfigs) -> list[Any]: ...
+```
+
+*   **Purpose:** Execute custom functions defined in your environment controller (the Python code running inside the Docker container or remote instance). This is how `setup` and `evaluate` configurations in a `Task` are ultimately executed.
+*   **Usage:** You provide a configuration (string, tuple, dict, or list) matching the `HudStyleConfigs` format. The SDK sends this to the environment controller, which runs the specified function(s) with the given arguments.
+*   **When to Use:**
+    *   Triggering custom evaluation logic not suitable for the standard `evaluate` attribute.
+    *   Running specific diagnostic or state-setting functions within your custom environment controller during development or debugging.
+    *   Implementing complex, multi-step setup or teardown procedures beyond what's easily defined in the `Task` `setup`.
+
+```python
+from hud.task import Task
+from hud import gym
+
+# Assume a custom environment controller has a function 'get_system_load()'
+task = Task(prompt="Check system load", gym=...) # Using a CustomGym spec
+
+env = await gym.make(task)
+
+# Manually invoke the custom function
+# Use the dictionary format for clarity
+config = {"function": "get_system_load", "args": []}
+results = await env._invoke_all(config)
+system_load = results[0] # _invoke_all returns a list of results
+
+print(f"Current system load: {system_load}")
+
+await env.close()
+```
+
+## `execute`
+
+The `client.execute()` method (accessible via `env.client.execute()` if `env.client` is a `DockerClient` subclass like `LocalDockerClient` or `RemoteDockerClient`) allows running arbitrary shell commands *inside* the environment container.
+
+```python
+# Assuming env.client is a LocalDockerClient or RemoteDockerClient
+# Example: List files in the container's /tmp directory
+result: ExecuteResult = await env.client.execute(
+    command=["ls", "-la", "/tmp"],
+    timeout=10 # Timeout in seconds
+)
+
+print("STDOUT:", result['stdout'].decode())
+if result['stderr']:
+    print("STDERR:", result['stderr'].decode())
+print("Exit Code:", result['exit_code'])
+```
+
+*   **Purpose:** Directly interact with the environment's shell.
+*   **Availability:** Primarily available for Docker-based environments (local or remote custom). Standard remote environments (like `"hud-browser"`) might not support arbitrary command execution via this method.
+*   **When to Use:**
+    *   **Debugging:** Checking file existence, process status, or network connectivity *inside* the container.
+    *   **Complex Setup:** Running intricate setup scripts or commands that are difficult to express using the standard `setup` configuration.
+    *   **Local Development:** Installing packages or modifying the container state interactively during development of a custom environment.
+*   **Returns:** An `ExecuteResult` typed dictionary containing `stdout` (bytes), `stderr` (bytes), and `exit_code` (int).
+
+## `_setup`
+
+```python
+async def _setup(self, config: HudStyleConfigs | None = None) -> None: ...
+```
+
+*   **Purpose:** Executes the setup configuration for the environment.
+*   **Execution:** This is normally called *automatically* by `hud.gym.make(task)` if the provided `task` has a `setup` configuration.
+*   **When to Use Manually:**
+    *   **Debugging:** To re-run setup steps on an already created environment instance without recreating it entirely.
+    *   **Custom Flow:** If you create an environment *without* an initial task (`env = await gym.make("gym-id")`) and later want to apply setup steps before starting agent interaction (though `env.reset(task=...)` might be more idiomatic).
+    *   To override the task's default setup by passing a different `config`.
+
+```python
+# Example: Manually re-running setup (less common)
+task = Task(prompt="...", gym="...", setup=("goto", "initial_page.com"))
+env = await gym.make(task) # Initial setup runs here
+
+# ... some interaction ...
+
+print("Re-running setup...")
+await env._setup() # Re-runs the setup defined in the task
+
+# Or run different setup steps
+await env._setup( ("goto", "another_page.com") )
+
+await env.close()
+```
+
+These advanced methods provide deeper control when the standard `step`/`evaluate`/`close` cycle isn't sufficient. Use them carefully, especially `execute`, as direct shell access can make scenarios less reproducible if not managed properly.