# `HuggingfaceClient.Hub.Cache`
[🔗](https://github.com/huggingface/huggingface_client/blob/v0.1.0/lib/huggingface_client/hub/storage/cache.ex#L1)

HuggingFace Hub local cache management.

The Hub cache stores downloaded model/dataset files in a structured
directory layout compatible with the Python `huggingface_hub` library.
Cache layout mirrors Python's `~/.cache/huggingface/hub/` structure.

## Cache layout

```
~/.cache/huggingface/hub/
  models--gpt2/
    refs/
      main          ← contains commit SHA
    snapshots/
      abc123def.../
        config.json
        model.safetensors
  datasets--rajpurkar--squad/
    refs/
      main
    snapshots/
      def456.../
        dataset_info.json
```

## Example

    # Scan the cache and get usage info
    {:ok, cache} = HuggingfaceClient.scan_cache()
    IO.puts("Total size: #{cache["size_on_disk"]} bytes")

    # List all cached repos
    Enum.each(cache["repos"], fn repo ->
      IO.puts("#{repo["repo_id"]} (#{repo["size_on_disk"]} bytes)")
    end)

    # Delete revisions to free space
    :ok = HuggingfaceClient.delete_cached_revision("gpt2",
      revision: "old-sha-abc123",
      type: :model
    )

# `default_cache_dir`

```elixir
@spec default_cache_dir() :: String.t()
```

Returns the default cache directory path.

Respects `HF_HUB_CACHE`, `HUGGINGFACE_HUB_CACHE`, `HF_HOME`,
and `XDG_CACHE_HOME` environment variables.

## Example

    dir = HuggingfaceClient.default_cache_dir()
    IO.puts("Cache: #{dir}")

# `delete_repo_cache`

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

Deletes all cached files for a repository.

## Options

- `:type` — repo type (default: `:model`)
- `:cache_dir`

## Example

    :ok = HuggingfaceClient.delete_cached_repo("old-model",
      type: :model
    )

# `delete_revision`

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

Deletes a specific cached revision for a repo to free disk space.

## Options

- `:revision` — commit SHA to delete (required)
- `:type` — repo type (`:model`, `:dataset`, `:space`) (default: `:model`)
- `:cache_dir` — override cache directory

## Example

    :ok = HuggingfaceClient.delete_cached_revision("gpt2",
      revision: "abc123def456...",
      type: :model
    )

# `scan`

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

Scans the local HF cache and returns usage information.

Returns a map with:
- `"size_on_disk"` — total bytes used
- `"repos"` — list of cached repo information
- `"cache_dir"` — path to the cache directory

## Options

- `:cache_dir` — override the default cache directory

## Example

    {:ok, cache} = HuggingfaceClient.scan_cache()
    IO.puts("Cached repos: #{length(cache["repos"])}")
    IO.puts("Total size: #{cache["size_on_disk_str"]}")

---

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