The hud.env module (primarily hud.env.environment) provides the core classes for representing and interacting with runtime environments.

See the Environment Concepts page for explanations and usage examples.

​

Classes

​

Environment

class Environment(pydantic.BaseModel):
    metadata: dict[str, Any]
    client: Client # Internal client (LocalDocker, RemoteDocker, Remote)
    url: str | None
    live_url: str | None
    task: Task | None
    build_data: dict[str, Any]

    async def step(
        self, actions: list[CLA] | None = None
    ) -> tuple[Observation, float, bool, dict[str, Any]]: ...

    async def evaluate(
        self, config: HudStyleConfigs | None = None
    ) -> Any: ...

    async def reset(
        self, configs: HudStyleConfigs | None = None
    ) -> tuple[Observation, dict[str, Any]]: ...

    async def get_urls(self) -> dict[str, Any]: ...

    async def close(self) -> None: ...

    # Internal/Advanced Methods
    # async def _setup(self, config: HudStyleConfigs | None = None) -> None: ...
    # async def _invoke_all(self, configs: HudStyleConfigs) -> list[Any]: ...

Represents a running instance (browser, OS) where an Agent interacts. Environments are typically created using hud.gym.make() rather than direct construction.

Attributes:

• metadata (dict[str, Any]): Metadata associated with this environment instance.
• client (Client): Internal client instance responsible for communicating with the environment runtime (local or remote).
• url (str | None): Primary access URL for the environment (if applicable).
• live_url (str | None): URL for live viewing/streaming (if applicable, obtained via get_urls).
• task (Task | None): The Task currently associated with this environment.
• build_data (dict[str, Any]): Data related to the environment build process.

Key Methods:

• step(self, actions: list[CLA] | None = None): Executes agent actions or gets the initial state.
  • Parameters:
    • actions: List of CLA actions, or None to get initial observation.
  • Returns: (Observation, reward, terminated, info) tuple. reward is typically 0 unless overridden by custom logic. terminated is typically False.
• evaluate(self, config: HudStyleConfigs | None = None): Runs the evaluation logic defined in the Task (or the provided config).
  • Parameters:
    • config: Optional override for evaluation logic using Configuration Styles.
  • Returns: The result from the evaluation function(s).
• reset(self, configs: HudStyleConfigs | None = None): Resets the environment state, usually running setup logic.
  • Parameters:
    • configs: Optional override for setup logic.
  • Returns: (Observation, info) tuple after resetting. (Note: gym.make(task) handles initial setup; direct reset is less common).
• get_urls(self): Fetches access URLs (url, live_url) for the environment.
  • Returns: dict containing URLs.
• close(self): Terminates the environment instance and cleans up resources. Saves Trajectory if linked to a Job.

​

Observation

class Observation(pydantic.BaseModel):
    screenshot: str | None = None
    text: str | None = None

Represents the state observed by the agent at a given step.

Attributes:

• screenshot (str | None): Base64-encoded PNG string of the screen.
• text (str | None): Textual observation from the environment (e.g., accessibility info, terminal output).

​

TaskResult

The TaskResult class represents the result of a task step.

​

Attributes

• observation (Observation): The current observation
• reward (float): Reward value from the step
• terminated (bool): Whether the task is complete
• info (dict[str, Any]): Additional information from the environment