# `HfHub.Spaces`
[🔗](https://github.com/North-Shore-AI/hf_hub_ex/blob/v0.3.1/lib/hf_hub/spaces.ex#L1)

Space management API for HuggingFace Spaces.

Provides runtime control, secrets, variables, and hardware configuration.

## Hardware Options

  * `:cpu_basic` - Free CPU
  * `:cpu_upgrade` - Upgraded CPU
  * `:t4_small` - T4 GPU (small)
  * `:t4_medium` - T4 GPU (medium)
  * `:a10g_small` - A10G GPU (small)
  * `:a10g_large` - A10G GPU (large)
  * `:a100_large` - A100 GPU
  * `:zero_a10g` - ZeroGPU A10G

## Storage Options

  * `:small` - Small persistent storage
  * `:medium` - Medium persistent storage
  * `:large` - Large persistent storage

## Examples

    # Get runtime info
    {:ok, runtime} = HfHub.Spaces.get_runtime("user/my-space")

    # Request GPU hardware
    {:ok, runtime} = HfHub.Spaces.request_hardware("user/my-space", :t4_small)

    # Add a secret
    :ok = HfHub.Spaces.add_secret("user/my-space", "API_KEY", "secret_value")

    # Pause and restart
    {:ok, _} = HfHub.Spaces.pause("user/my-space")
    {:ok, _} = HfHub.Spaces.restart("user/my-space")

# `hardware`

```elixir
@type hardware() ::
  :cpu_basic
  | :cpu_upgrade
  | :t4_small
  | :t4_medium
  | :a10g_small
  | :a10g_large
  | :a100_large
  | :zero_a10g
```

# `storage`

```elixir
@type storage() :: :small | :medium | :large
```

# `add_secret`

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

Adds or updates a secret.

Secrets are encrypted and not visible after creation.

## Arguments

  * `repo_id` - Repository ID
  * `key` - Secret name
  * `value` - Secret value
  * `opts` - Request options

## Options

  * `:token` - Authentication token
  * `:description` - Optional description

## Examples

    :ok = HfHub.Spaces.add_secret("user/my-space", "API_KEY", "secret_value")
    :ok = HfHub.Spaces.add_secret("user/my-space", "API_KEY", "value",
            description: "API key for external service")

# `add_variable`

```elixir
@spec add_variable(String.t(), String.t(), String.t(), keyword()) ::
  {:ok, HfHub.Spaces.SpaceVariable.t()} | {:error, term()}
```

Adds or updates a variable.

Variables are visible in the Space settings.

## Arguments

  * `repo_id` - Repository ID
  * `key` - Variable name
  * `value` - Variable value
  * `opts` - Request options

## Options

  * `:token` - Authentication token
  * `:description` - Optional description

## Examples

    {:ok, var} = HfHub.Spaces.add_variable("user/my-space", "DEBUG", "true")

# `delete_secret`

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

Deletes a secret.

## Arguments

  * `repo_id` - Repository ID
  * `key` - Secret name to delete
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    :ok = HfHub.Spaces.delete_secret("user/my-space", "API_KEY")

# `delete_storage`

```elixir
@spec delete_storage(
  String.t(),
  keyword()
) :: {:ok, HfHub.Spaces.SpaceRuntime.t()} | {:error, term()}
```

Deletes persistent storage.

**Warning**: This is destructive and cannot be undone.

## Arguments

  * `repo_id` - Repository ID
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    {:ok, runtime} = HfHub.Spaces.delete_storage("user/my-space")

# `delete_variable`

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

Deletes a variable.

## Arguments

  * `repo_id` - Repository ID
  * `key` - Variable name to delete
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    :ok = HfHub.Spaces.delete_variable("user/my-space", "DEBUG")

# `duplicate`

```elixir
@spec duplicate(
  String.t(),
  keyword()
) :: {:ok, HfHub.Repo.RepoUrl.t()} | {:error, term()}
```

Duplicates a Space to a new repository.

## Arguments

  * `from_id` - Source Space repository ID
  * `opts` - Request options

## Options

  * `:token` - Authentication token
  * `:to_id` - Target repository ID (default: same name in user namespace)
  * `:private` - Make duplicate private (default: false)
  * `:hardware` - Hardware for duplicate
  * `:storage` - Storage for duplicate
  * `:secrets` - List of secrets to copy (maps with "key" and "value")
  * `:variables` - List of variables to copy (maps with "key" and "value")

## Examples

    {:ok, repo_url} = HfHub.Spaces.duplicate("gradio/hello_world")
    {:ok, repo_url} = HfHub.Spaces.duplicate("gradio/hello_world",
                        to_id: "user/my-copy", private: true)

# `get_runtime`

```elixir
@spec get_runtime(
  String.t(),
  keyword()
) :: {:ok, HfHub.Spaces.SpaceRuntime.t()} | {:error, term()}
```

Gets runtime information for a Space.

## Arguments

  * `repo_id` - Repository ID (e.g., "user/my-space")
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    {:ok, runtime} = HfHub.Spaces.get_runtime("user/my-space")
    runtime.stage  # => :running
    runtime.hardware  # => "cpu-basic"

# `get_variables`

```elixir
@spec get_variables(
  String.t(),
  keyword()
) ::
  {:ok, %{required(String.t()) => HfHub.Spaces.SpaceVariable.t()}}
  | {:error, term()}
```

Gets all variables for a Space.

## Arguments

  * `repo_id` - Repository ID
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    {:ok, vars} = HfHub.Spaces.get_variables("user/my-space")
    vars["MY_VAR"].value  # => "some_value"

# `pause`

```elixir
@spec pause(
  String.t(),
  keyword()
) :: {:ok, HfHub.Spaces.SpaceRuntime.t()} | {:error, term()}
```

Pauses a running Space.

A paused Space stops using resources but retains its configuration.

## Arguments

  * `repo_id` - Repository ID
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    {:ok, runtime} = HfHub.Spaces.pause("user/my-space")

# `request_hardware`

```elixir
@spec request_hardware(String.t(), hardware(), keyword()) ::
  {:ok, HfHub.Spaces.SpaceRuntime.t()} | {:error, term()}
```

Requests hardware upgrade or downgrade.

## Arguments

  * `repo_id` - Repository ID
  * `hardware` - Hardware type (see module docs)
  * `opts` - Request options

## Options

  * `:token` - Authentication token
  * `:sleep_time` - Auto-sleep timeout in seconds

## Examples

    {:ok, runtime} = HfHub.Spaces.request_hardware("user/my-space", :t4_small)
    {:ok, runtime} = HfHub.Spaces.request_hardware("user/my-space", :cpu_basic,
                       sleep_time: 300)

# `request_storage`

```elixir
@spec request_storage(String.t(), storage(), keyword()) ::
  {:ok, HfHub.Spaces.SpaceRuntime.t()} | {:error, term()}
```

Requests persistent storage.

## Arguments

  * `repo_id` - Repository ID
  * `storage` - Storage tier (`:small`, `:medium`, or `:large`)
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    {:ok, runtime} = HfHub.Spaces.request_storage("user/my-space", :small)

# `restart`

```elixir
@spec restart(
  String.t(),
  keyword()
) :: {:ok, HfHub.Spaces.SpaceRuntime.t()} | {:error, term()}
```

Restarts a Space.

## Arguments

  * `repo_id` - Repository ID
  * `opts` - Request options

## Options

  * `:token` - Authentication token
  * `:factory_reboot` - Full factory reset (default: false)

## Examples

    {:ok, runtime} = HfHub.Spaces.restart("user/my-space")
    {:ok, runtime} = HfHub.Spaces.restart("user/my-space", factory_reboot: true)

# `set_sleep_time`

```elixir
@spec set_sleep_time(String.t(), integer(), keyword()) ::
  {:ok, HfHub.Spaces.SpaceRuntime.t()} | {:error, term()}
```

Sets the auto-sleep timeout.

## Arguments

  * `repo_id` - Repository ID
  * `seconds` - Timeout in seconds, or -1 to disable (requires paid hardware)
  * `opts` - Request options

## Options

  * `:token` - Authentication token

## Examples

    {:ok, runtime} = HfHub.Spaces.set_sleep_time("user/my-space", 300)
    {:ok, runtime} = HfHub.Spaces.set_sleep_time("user/my-space", -1)  # Never sleep

---

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