# `HuggingfaceClient.Hub.Compute.Jobs`
[🔗](https://github.com/huggingface/huggingface_client/blob/v0.1.0/lib/huggingface_client/hub/compute/jobs.ex#L1)

HuggingFace Hub Jobs API — run Docker workloads on HF infrastructure.

Jobs support CPUs, GPUs, TPUs, volume mounts, UV scripts, and scheduled execution.

## Hardware flavors

- **CPU**: `"cpu-basic"`, `"cpu-upgrade"`
- **GPU**: `"t4-small"`, `"t4-medium"`, `"l4x1"`, `"l4x4"`, `"a10g-small"`,
           `"a10g-large"`, `"a10g-largex2"`, `"a10g-largex4"`, `"a100-large"`
- **TPU**: `"v5e-1x1"`, `"v5e-2x2"`, `"v5e-2x4"`

## Example

    {:ok, job} = HuggingfaceClient.run_job(
      image:   "python:3.12",
      command: ["python", "-c", "print('Hello from HF infra!')"],
      flavor:  "cpu-basic",
      access_token: "hf_..."
    )
    result = HuggingfaceClient.fetch_job_logs(job["id"], access_token: "hf_...")
    |> Enum.each(&IO.puts/1)

# `cancel`

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

Cancels a running job.

# `create_scheduled`

```elixir
@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`

# `delete_scheduled`

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

Deletes a scheduled job.

# `fetch_logs`

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

# `fetch_metrics`

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

# `get_scheduled`

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

Gets a specific scheduled job.

# `inspect_job`

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

Gets the current status and details of a job.

# `list`

```elixir
@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`

# `list_hardware`

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

Lists available hardware flavors for jobs.

# `list_scheduled`

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

Lists scheduled jobs.

# `run`

```elixir
@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`

# `run_uv`

```elixir
@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`

# `wait`

```elixir
@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`

---

*Consult [api-reference.md](api-reference.md) for complete listing*