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

Elixir client for HuggingFace Hub.

`HfHub` provides a comprehensive interface to the HuggingFace Hub API,
enabling Elixir applications to access models, datasets, and spaces.

## Features

- **Hub API Client** — Fetch metadata for models, datasets, and spaces
- **File Downloads** — Stream files from HuggingFace repositories with resume support
- **Smart Caching** — Local file caching with LRU eviction and integrity checks
- **Filesystem Utilities** — Manage local HuggingFace cache directory structure
- **Authentication** — Token-based authentication for private repositories

## Quick Start

    # Get model information
    {:ok, model_info} = HfHub.Api.model_info("bert-base-uncased")

    # Download a model file
    {:ok, path} = HfHub.Download.hf_hub_download(
      repo_id: "bert-base-uncased",
      filename: "config.json",
      repo_type: :model
    )

    # Check cache
    cached? = HfHub.Cache.cached?(
      repo_id: "bert-base-uncased",
      filename: "config.json"
    )

## Configuration

Per Elixir runtime-configuration best practices, this library reads only
from `Application.get_env(:hf_hub, ...)`. No OS environment variables
are read by library code. Hosts that want the historical env-var
shortcuts should wire them in `config/runtime.exs`:

    # config/runtime.exs
    import Config

    if token = System.get_env("HF_TOKEN") do
      config :hf_hub, token: token
    end

    cond do
      dir = System.get_env("HF_HUB_CACHE") ->
        config :hf_hub, cache_dir: dir

      dir = System.get_env("HF_HOME") ->
        config :hf_hub, cache_dir: Path.join(dir, "hub")

      true ->
        :ok
    end

    if System.get_env("HF_HUB_OFFLINE") in ~w(1 true) do
      config :hf_hub, offline: true
    end

Compile-time configuration also works for static values:

    # config/config.exs
    config :hf_hub,
      endpoint: "https://huggingface.co",
      cache_dir: Path.expand("~/.cache/huggingface")

## Modules

- `HfHub.Api` — Hub API client (models, datasets, spaces)
- `HfHub.Download` — File download with caching
- `HfHub.Cache` — Cache management and statistics
- `HfHub.FS` — Filesystem utilities for cache
- `HfHub.Auth` — Authentication and authorization
- `HfHub.Hub` — Bumblebee-compatible ETag-based caching
- `HfHub.Repository` — Repository reference types
- `HfHub.RepoFiles` — Repository file listing with ETags

# `filename`

```elixir
@type filename() :: String.t()
```

# `repo_id`

```elixir
@type repo_id() :: String.t()
```

# `repo_type`

```elixir
@type repo_type() :: :model | :dataset | :space
```

# `repository`

```elixir
@type repository() :: HfHub.Repository.t()
```

A repository reference (Bumblebee-compatible).

Can be either:
  * `{:hf, repository_id}` - HuggingFace repository
  * `{:hf, repository_id, opts}` - HuggingFace repository with options
  * `{:local, directory}` - Local directory

# `revision`

```elixir
@type revision() :: String.t()
```

# `cached_download`

# `file_listing_url`

# `file_url`

# `get_repo_files`

# `is_offline_mode`

> This function is deprecated. Use offline_mode?/0 instead.

```elixir
@spec is_offline_mode() :: boolean()
```

Alias for `offline_mode?/0` for Python compatibility.

Deprecated: Use `offline_mode?/0` instead.

# `offline_mode?`

```elixir
@spec offline_mode?() :: boolean()
```

Check if offline mode is enabled.

Offline mode is read from `Application.get_env(:hf_hub, :offline, false)`.
Hosts wire `HF_HUB_OFFLINE` into that key from `config/runtime.exs` per
the `## Configuration` section above. Library code no longer reads the
environment directly.

When offline mode is enabled, no network requests are made and only
cached files are used.

## Examples

    if HfHub.offline_mode?() do
      IO.puts("Running in offline mode")
    end

# `try_to_load_from_cache`

```elixir
@spec try_to_load_from_cache(repo_id(), filename(), keyword()) ::
  {:ok, Path.t()} | {:error, :not_cached}
```

Try to load a file from cache without network access.

Returns `{:ok, path}` if the file exists in cache, `{:error, :not_cached}` otherwise.
Does not attempt any network requests, even if offline mode is not enabled.

This is useful when you want to check if a file is available locally
before deciding whether to download it.

## Arguments

  * `repo_id` - Repository ID (e.g., "bert-base-uncased")
  * `filename` - Name of the file to look up
  * `opts` - Options

## Options

  * `:revision` - Git revision. Defaults to `"main"`.
  * `:repo_type` - Type of repository (`:model`, `:dataset`, or `:space`). Defaults to `:model`.

## Examples

    case HfHub.try_to_load_from_cache("bert-base-uncased", "config.json") do
      {:ok, path} ->
        # File is cached, use it
        File.read!(path)
      {:error, :not_cached} ->
        # File not cached, need to download
        {:ok, path} = HfHub.Download.hf_hub_download(
          repo_id: "bert-base-uncased",
          filename: "config.json"
        )
        File.read!(path)
    end

---

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