@spec cancel(
  String.t(),
  keyword()
) :: :ok | {:error, Exception.t()}

Cancels a running job.

@spec create_scheduled(keyword()) :: {:ok, map()} | {:error, Exception.t()}

Creates a cron-scheduled job.

Options

• :schedule — cron expression or preset, e.g. "@daily", "0 9 * * 1" (required)
• :image — Docker image (required unless :space_id)
• :command, :flavor, :env, :secrets, :namespace, :access_token

@spec delete_scheduled(
  String.t(),
  keyword()
) :: :ok | {:error, Exception.t()}

Deletes a scheduled job.

@spec fetch_logs(
  String.t(),
  keyword()
) :: Enumerable.t()

Returns a stream of log lines from a job.

Example

result = HuggingfaceClient.fetch_job_logs(job["id"], access_token: "hf_...")
|> Enum.each(&IO.puts/1)

@spec fetch_metrics(
  String.t(),
  keyword()
) :: Enumerable.t()

Returns a stream of resource usage metrics from a job (CPU, memory, GPU).

Example

result = HuggingfaceClient.fetch_job_metrics("job-id", access_token: "hf_...")
|> Enum.each(fn m -> IO.puts("CPU: #{m["cpu_usage_pct"]}%") end)

@spec get_scheduled(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}

Gets a specific scheduled job.

@spec inspect_job(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}

Gets the current status and details of a job.

@spec list(keyword()) :: {:ok, [map()]} | {:error, Exception.t()}

Lists jobs for the authenticated user or a specific namespace.

Options

• :namespace — user or org
• :status — filter: "RUNNING", "COMPLETED", "ERROR", "CANCELLED"
• :limit
• :access_token

@spec list_hardware(keyword()) :: {:ok, [map()]} | {:error, Exception.t()}

Lists available hardware flavors for jobs.

@spec list_scheduled(keyword()) :: {:ok, [map()]} | {:error, Exception.t()}

Lists scheduled jobs.

@spec run(keyword()) :: {:ok, map()} | {:error, Exception.t()}

Runs a Docker-based compute job on HF infrastructure.

Options

• :image — Docker image (required), e.g. "python:3.12" or "hf.co/spaces/user/space" for a Space image
• :command — command list, e.g. ["python", "train.py"]
• :flavor — hardware (default: "cpu-basic")
• :timeout — "2h", "30m", or seconds as integer
• :env — environment variables map
• :secrets — secrets map
• :volumes — list of volume mount maps
• :namespace — user or org (defaults to authenticated user)
• :access_token

@spec run_uv(keyword()) :: {:ok, map()} | {:error, Exception.t()}

Runs a UV Python script on HF infrastructure.

UV scripts can declare their dependencies inline using PEP 723 syntax.

Options

• :script — path to local script or URL to remote script (required)
• :script_args — arguments to pass to the script
• :dependencies — extra pip packages to install
• :python_version — Python version (e.g. "3.12")
• :flavor — hardware flavor
• :timeout, :env, :secrets, :namespace, :access_token

@spec wait(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Exception.t()}

Polls a job until it reaches a terminal state (COMPLETED, ERROR, CANCELLED).

Options

• :poll_interval — seconds between polls (default: 10)
• :timeout — max wait seconds (default: 3_600)
• :access_token