HuggingFace Hub API client.
Provides functions to interact with the HuggingFace Hub API for fetching metadata about models, datasets, and spaces.
Examples
# Get model information
{:ok, model_info} = HfHub.Api.model_info("bert-base-uncased")
# Get dataset information
{:ok, dataset_info} = HfHub.Api.dataset_info("squad")
# List models with filters
{:ok, models} = HfHub.Api.list_models(filter: "text-classification", sort: "downloads")
# List files in a repository
{:ok, files} = HfHub.Api.list_files("bert-base-uncased", repo_type: :model)Summary
Functions
Gets the available configuration names for a dataset.
Fetches information about a dataset from the HuggingFace Hub.
Lists available splits for a dataset config.
Extracts configuration names from dataset card_data.
Lists datasets from the HuggingFace Hub with optional filters.
Lists files in a repository.
Lists models from the HuggingFace Hub with optional filters.
Lists repository tree entries (files and folders).
Fetches information about a model from the HuggingFace Hub.
Fetches information about a space from the HuggingFace Hub.
Types
@type dataset_info() :: %{ id: String.t(), author: String.t() | nil, sha: String.t(), downloads: non_neg_integer(), likes: non_neg_integer(), tags: [String.t()], siblings: [file_info()], created_at: DateTime.t(), updated_at: DateTime.t() }
@type file_info() :: %{ rfilename: String.t(), size: non_neg_integer(), lfs: map() | nil }
@type model_info() :: %{ id: String.t(), author: String.t() | nil, sha: String.t(), downloads: non_neg_integer(), likes: non_neg_integer(), tags: [String.t()], pipeline_tag: String.t() | nil, siblings: [file_info()], created_at: DateTime.t(), updated_at: DateTime.t() }
@type space_info() :: %{ id: String.t(), author: String.t() | nil, sha: String.t(), likes: non_neg_integer(), tags: [String.t()], sdk: String.t(), created_at: DateTime.t(), updated_at: DateTime.t() }
@type tree_entry() :: %{ type: :file | :folder, path: String.t(), size: non_neg_integer() | nil, lfs: map() | nil, oid: String.t() | nil }
Functions
@spec dataset_configs( HfHub.repo_id(), keyword() ) :: {:ok, [String.t()]} | {:error, term()}
Gets the available configuration names for a dataset.
Configurations (also called subsets) represent different versions or splits
of a dataset. For example, openai/gsm8k has "main" and "socratic" configs.
Options
:token- Authentication token. If not provided, uses configured token.
Examples
{:ok, configs} = HfHub.Api.dataset_configs("openai/gsm8k")
# => {:ok, ["main", "socratic"]}
{:ok, configs} = HfHub.Api.dataset_configs("imdb")
# => {:ok, ["plain_text"]}@spec dataset_info( HfHub.repo_id(), keyword() ) :: {:ok, dataset_info()} | {:error, term()}
Fetches information about a dataset from the HuggingFace Hub.
Options
:revision- Git revision (branch, tag, or commit hash). Defaults to"main".:token- Authentication token. If not provided, uses configured token.
Examples
{:ok, info} = HfHub.Api.dataset_info("squad")
{:ok, info} = HfHub.Api.dataset_info("squad", revision: "main")@spec dataset_splits( HfHub.repo_id(), keyword() ) :: {:ok, [String.t()]} | {:error, term()}
Lists available splits for a dataset config.
Options
:config- Dataset config name (defaults to inferred config).:revision- Git revision. Defaults to"main".:token- Authentication token.
Extracts configuration names from dataset card_data.
Handles both the modern "configs" format and legacy "dataset_config_names" format.
Examples
iex> HfHub.Api.extract_config_names(%{"configs" => [%{"config_name" => "main"}]})
["main"]
iex> HfHub.Api.extract_config_names(%{"dataset_config_names" => ["train", "test"]})
["train", "test"]
iex> HfHub.Api.extract_config_names(nil)
[]@spec list_datasets(keyword()) :: {:ok, [dataset_info()]} | {:error, term()}
Lists datasets from the HuggingFace Hub with optional filters.
Options
:filter- Filter by task or other criteria:sort- Sort by field (e.g., "downloads", "likes", "updated"):direction- Sort direction (:ascor:desc):limit- Maximum number of results:author- Filter by author
Examples
{:ok, datasets} = HfHub.Api.list_datasets(sort: "downloads", limit: 10)@spec list_files( HfHub.repo_id(), keyword() ) :: {:ok, [file_info()]} | {:error, term()}
Lists files in a repository.
Options
:repo_type- Type of repository (:model,:dataset, or:space). Defaults to:model.:revision- Git revision. Defaults to"main".:recursive- List files recursively. Defaults totruefor datasets.:path_in_repo- Subdirectory path to list.:token- Authentication token.
Examples
{:ok, files} = HfHub.Api.list_files("bert-base-uncased", repo_type: :model)@spec list_models(keyword()) :: {:ok, [model_info()]} | {:error, term()}
Lists models from the HuggingFace Hub with optional filters.
Options
:filter- Filter by task, library, or other criteria:sort- Sort by field (e.g., "downloads", "likes", "updated"):direction- Sort direction (:ascor:desc):limit- Maximum number of results:author- Filter by author
Examples
{:ok, models} = HfHub.Api.list_models(filter: "text-classification", limit: 10)@spec list_repo_tree( HfHub.repo_id(), keyword() ) :: {:ok, [tree_entry()]} | {:error, term()}
Lists repository tree entries (files and folders).
Options
:repo_type- Type of repository (:model,:dataset, or:space). Defaults to:model.:revision- Git revision. Defaults to"main".:path_in_repo- Subdirectory path to list.:recursive- List recursively. Defaults tofalse.:expand- Request expanded metadata. Defaults tofalse.:token- Authentication token.
@spec model_info( HfHub.repo_id(), keyword() ) :: {:ok, model_info()} | {:error, term()}
Fetches information about a model from the HuggingFace Hub.
Options
:revision- Git revision (branch, tag, or commit hash). Defaults to"main".:token- Authentication token. If not provided, uses configured token.
Examples
{:ok, info} = HfHub.Api.model_info("bert-base-uncased")
{:ok, info} = HfHub.Api.model_info("bert-base-uncased", revision: "main")@spec space_info( HfHub.repo_id(), keyword() ) :: {:ok, space_info()} | {:error, term()}
Fetches information about a space from the HuggingFace Hub.
Options
:revision- Git revision (branch, tag, or commit hash). Defaults to"main".:token- Authentication token. If not provided, uses configured token.
Examples
{:ok, info} = HfHub.Api.space_info("user/space-name")