The hud.job module provides the @job decorator, functions to manage Jobs (create_job, load_job), and the Job class itself.

See the Job Concepts page for explanations and usage examples.

​
Decorators

​
@job

def job(
    name: str,
    metadata: dict[str, Any] | None = None
) -> Callable[[T], T]:

Decorator for async functions to automatically create a Job and associate all environments created within that function call with the job.

Parameters:

  • name (str): The name for the created Job.
  • metadata (dict[str, Any] | None, optional): Metadata to store with the Job.

Returns:

  • A decorator that wraps the async function.

​
Module Functions

​
create_job

async def create_job(
    name: str,
    gym_id: str | None = None,
    evalset_id: str | None = None,
    metadata: dict[str, Any] | None = None
) -> Job:

Creates a new Job instance explicitly.

Parameters:

  • name (str): The name for the new Job.
  • gym_id (str | None, optional): Optional Gym ID to associate.
  • evalset_id (str | None, optional): Optional EvalSet ID to associate.
  • metadata (dict[str, Any] | None, optional): Metadata to store with the Job.

Returns:

  • Job: The newly created Job object.

​
load_job

async def load_job(
    job_id: str,
    api_key: str | None = None
) -> Job:

Retrieves an existing Job by its ID from the HUD platform.

Parameters:

  • job_id (str): The unique ID of the Job to retrieve.
  • api_key (str | None, optional): HUD API key. If None, uses the key from hud.settings.

Returns:

  • Job: The retrieved Job object.

​
Classes

​
Job

class Job(pydantic.BaseModel):
    id: str
    name: str
    metadata: dict[str, Any] | None
    created_at: datetime.datetime
    status: str

    async def load_trajectories(
        self, *, api_key: str | None = None
    ) -> list[Trajectory]: ...

Represents a Job, typically obtained via @job, create_job, or load_job. Primarily used to access associated trajectories.

Attributes:

  • id (str): Unique identifier.
  • name (str): Job name.
  • metadata (dict[str, Any] | None): Associated metadata.
  • created_at (datetime.datetime): Creation timestamp.
  • status (str): Current status (e.g., “running”, “completed”).

Methods:

  • load_trajectories(self, *, api_key: str | None = None): Asynchronously loads all Trajectories associated with this Job instance. Requires HUD API key if not set globally. Returns a list of Trajectory objects.