HuggingfaceClient.Hub.Cache (huggingface_client v0.1.0)

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
)

Summary

Functions

default_cache_dir()

Returns the default cache directory path.

delete_repo_cache(repo_id, opts \\ [])

Deletes all cached files for a repository.

delete_revision(repo_id, opts \\ [])

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

scan(opts \\ [])

Scans the local HF cache and returns usage information.

Functions

default_cache_dir()

@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(repo_id, opts \\ [])

@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(repo_id, opts \\ [])

@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(opts \\ [])

@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"]}")