@spec auth_headers(keyword()) :: [{String.t(), String.t()}]

Build authentication headers from options or environment.

Checks for tokens in order: :token option, HF_TOKEN env var, HUGGING_FACE_HUB_TOKEN env var (legacy).

@spec build_download_url(String.t(), String.t(), keyword()) :: String.t()

Build the download URL for a file in a HuggingFace repository.

@spec cache_path(String.t(), String.t(), keyword()) :: String.t()

Build the local cache path for a model file.

The path is <cache_dir>/<repo_id>/<revision>/<filename>. revision is part of the key because otherwise pinning revision: "<sha>" returned whatever had been cached for main — the pin bought nothing, silently. It defaults to "main".

All three components are caller-supplied and become path components, so each is validated first: one that is absolute, empty, ".", "..", ~-prefixed, or contains a null byte would escape the cache and is rejected with an ArgumentError. download/3 performs the same validation but surfaces it as {:error, reason}.

@spec download(String.t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, String.t()}

Download a GGUF file from HuggingFace Hub, returning the local path.

An already-cached file is returned immediately, without contacting the Hub. There is no upstream revalidation — the ETag written to the <file>.etag sidecar is never read back — so pass force: true to refresh a cached file. The cache key includes :revision, so two revisions of the same file cache separately.

A fresh download is streamed into a randomly named temporary file opened with O_EXCL, verified against the SHA-256 HuggingFace publishes for the file, and only then renamed into place with mode 0o600. A missing published digest is a failure, not a warning — see :verify_checksum.

Options

• :cache_dir - Local cache directory. Defaults to ~/.cache/llama_cpp_ex/models/ or the LLAMA_CACHE_DIR environment variable.
• :token - HuggingFace API token. Defaults to HF_TOKEN environment variable.
• :revision - Git revision (branch, tag, or commit). Defaults to "main". Part of the cache key.
• :force - Force re-download even if cached. Defaults to false.
• :verify_checksum - Integrity policy. Defaults to true.
  • true — fail closed. The download is checked against the SHA-256 HuggingFace publishes, and a file the Hub lists without one is refused. Verification used to be downgradable by the metadata response itself: it fell back to a warning when siblings[].lfs.sha256 was absent, so stripping one JSON key was enough to have the bytes cached unverified.
  • :best_effort — warn and proceed when the Hub publishes no digest. For the rare non-LFS blob that is genuinely small enough to have none.
  • false — skip the check and the metadata request entirely. Logged as a warning.
• :proxy, :no_proxy - Proxy overrides. See the "Proxies" section above.

@spec filter_gguf_files([map()]) :: [%{filename: String.t(), size: integer()}]

Filter a list of HuggingFace siblings entries to only GGUF files.

Returns maps with :filename and :size.

@spec get_model_info(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, String.t()}

Get model repository metadata from HuggingFace Hub API.

Options

• :token - HuggingFace API token.

@spec list_gguf_files(
  String.t(),
  keyword()
) :: {:ok, [%{filename: String.t(), size: integer()}]} | {:error, String.t()}

List GGUF files available in a HuggingFace repository.

Returns a list of maps with :filename and :size (bytes).

Options

• :token - HuggingFace API token.

Examples

{:ok, files} = LlamaCppEx.Hub.list_gguf_files("Qwen/Qwen3-4B-GGUF")
Enum.each(files, fn f ->
  size_mb = Float.round(f.size / 1_000_000, 1)
  IO.puts("#{f.filename} (#{size_mb} MB)")
end)

@spec search(
  String.t(),
  keyword()
) :: {:ok, [map()]} | {:error, String.t()}

Search HuggingFace Hub for GGUF models.

Returns a list of model info maps with :id, :downloads, :likes, :last_modified, and :tags.

Options

• :limit - Maximum results. Defaults to 10.
• :sort - Sort by "downloads", "likes", or "lastModified". Defaults to "downloads".
• :direction - Sort direction, -1 for descending. Defaults to -1.
• :token - HuggingFace API token.
• :proxy, :no_proxy - Proxy overrides. See the "Proxies" section above.

Examples

{:ok, models} = LlamaCppEx.Hub.search("llama gguf q4")
Enum.each(models, fn m -> IO.puts("#{m.id} (#{m.downloads} downloads)") end)