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

HuggingFace Hub — complete API client for the HF platform.

The Hub is the central platform for sharing ML models, datasets, and Spaces.
This module provides a unified facade over all Hub services organized by category:

## Service categories

| Category | Module(s) | Functions |
|----------|-----------|-----------|
| **Authentication** | `Auth` | `who_am_i/1` |
| **Repositories** | `Repos`, `Commits`, `Files`, `Snapshots`, `Tags` | create, delete, upload, download |
| **Models** | `Models` | list_models, model_info |
| **Datasets** | `Datasets`, `DatasetViewer` | list, info, rows, search |
| **Spaces** | `Spaces` | runtime, secrets, hardware |
| **Discovery** | `Search`, `Collections`, `Papers` | search, trending |
| **Collaboration** | `Discussions`, `Webhooks` | PRs, comments, events |
| **Storage** | `Buckets`, `Cache`, `FileSystem` | S3-like, hf:// URIs |
| **Compute** | `Jobs`, `AutoTrain` | GPU workloads, training |
| **Deployment** | `Endpoints` | managed inference |
| **Enterprise** | `Organizations`, `GatedRepos`, `OAuth` | access control |
| **Evaluation** | `Evaluate`, `Leaderboards` | metrics, benchmarks |
| **Community** | `Users` | profiles, followers |
| **Metadata** | `Metadata` | model cards |

## Example

    # Search models
    HuggingfaceClient.Hub.list_models(
      task: "text-generation",
      sort: "downloads",
      limit: 10,
      access_token: "hf_..."
    )
    |> Enum.each(fn m -> IO.puts(m["id"]) end)

    # Upload a file
    {:ok, _} = HuggingfaceClient.Hub.upload_file("my-org/my-model",
      path: "README.md",
      content: "# My Model",
      access_token: "hf_..."
    )

    # Run a GPU job
    {:ok, job} = HuggingfaceClient.Hub.run_job(
      image: "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
      command: ["python", "train.py"],
      flavor: "a10g-small",
      access_token: "hf_..."
    )

# `accept_access_request`

Accepts a gated repo request.

# `add_collection_item`

Adds item to a collection.

# `add_space_secret`

Adds a Space secret.

# `add_space_variable`

Adds a Space environment variable.

# `audit_logs`

Returns audit logs for an organization.

# `auth_check`

Checks if a token has access to a repository.

# `autotrain_cancel`

Cancels an AutoTrain project.

# `autotrain_create`

```elixir
@spec autotrain_create(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Creates an AutoTrain project.

# `autotrain_list`

Lists AutoTrain projects.

# `autotrain_status`

Gets AutoTrain project status.

# `batch_bucket_files`

Batch upload/delete bucket files.

# `bucket_info`

Gets bucket info.

# `cancel_access_request`

Cancels a gated repo request.

# `cancel_job`

Cancels a job.

# `change_discussion_status`

Changes discussion status.

# `comment_discussion`

Comments on a discussion.

# `compute_metric`

Computes a metric.

# `compute_metrics`

```elixir
@spec compute_metrics(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Computes multiple metrics.

# `copy_files`

```elixir
@spec copy_files(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Copies files between hf:// locations.

# `create_branch`

```elixir
@spec create_branch(any(), any(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Creates a branch.

# `create_bucket`

Creates a bucket.

# `create_collection`

```elixir
@spec create_collection(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Creates a collection.

# `create_discussion`

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

Creates a discussion.

# `create_inference_endpoint`

```elixir
@spec create_inference_endpoint(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Creates an inference endpoint.

# `create_pull_request`

Creates a pull request.

# `create_repo`

Creates a new repository.

# `create_scheduled_job`

```elixir
@spec create_scheduled_job(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Creates a scheduled job.

# `create_tag`

Creates a tag.

# `create_webhook`

```elixir
@spec create_webhook(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Creates a webhook.

# `dataset_info`

Gets detailed info about a dataset.

# `dataset_tags`

Returns all dataset tags.

# `dataset_viewer_configs`

Lists dataset configs.

# `dataset_viewer_features`

Returns feature schema.

# `dataset_viewer_first_rows`

Returns first rows of a split.

# `dataset_viewer_info`

Returns dataset info.

# `dataset_viewer_is_valid?`

```elixir
@spec dataset_viewer_is_valid?(
  any(),
  keyword()
) :: {:ok, term()} | {:error, Exception.t()}
```

Checks if a dataset is in the Dataset Viewer.

# `dataset_viewer_parquet`

Returns Parquet file URLs.

# `dataset_viewer_rows`

Returns paginated rows.

# `dataset_viewer_search`

Searches dataset rows.

# `dataset_viewer_size`

Returns dataset size.

# `dataset_viewer_splits`

Lists dataset splits.

# `dataset_viewer_statistics`

Returns column statistics.

# `default_cache_dir`

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

Default cache directory.

# `delete_branch`

```elixir
@spec delete_branch(any(), any(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Deletes a branch.

# `delete_bucket`

Deletes a bucket.

# `delete_cached_repo`

Deletes all cached files for a repo.

# `delete_cached_revision`

Deletes a cached revision.

# `delete_collection`

Deletes a collection.

# `delete_collection_item`

Deletes item from a collection.

# `delete_file`

Deletes a file.

# `delete_files`

Deletes multiple files.

# `delete_inference_endpoint`

Deletes an inference endpoint.

# `delete_repo`

Deletes a repository.

# `delete_scheduled_job`

Deletes a scheduled job.

# `delete_space_secret`

Deletes a Space secret.

# `delete_space_variable`

Deletes a Space environment variable.

# `delete_tag`

Deletes a tag.

# `delete_webhook`

Deletes a webhook.

# `download_file`

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

Downloads a file's content.

# `dpo_config`

```elixir
@spec dpo_config(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Builds a DPO alignment configuration.

# `duplicate_space`

Duplicates a Space.

# `edit_discussion_comment`

Edits a comment.

# `evaluate_model`

Evaluates a model on a dataset.

# `export_entries_as_dduf`

Exports specific entries as a DDUF file.

# `export_folder_as_dduf`

Exports a model folder as a DDUF file.

# `fetch_job_logs`

Streams job logs.

# `fetch_job_metrics`

Streams job metrics.

# `file_exists?`

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

Checks if a file exists.

# `full_finetune_config`

Builds a full fine-tuning configuration.

# `get_authenticated_user`

```elixir
@spec get_authenticated_user(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Gets authenticated user info.

# `get_bucket_file`

Downloads a bucket file.

# `get_collection`

Gets a collection.

# `get_discussion`

Gets a discussion.

# `get_inference_endpoint`

Gets an inference endpoint.

# `get_leaderboard`

Gets a leaderboard.

# `get_model_card_metadata`

Gets model card metadata.

# `get_repo_settings`

Gets repository settings.

# `get_space_runtime`

Gets Space runtime info.

# `get_space_variables`

Gets Space environment variables.

# `get_webhook`

Gets a webhook.

# `grant_access`

Grants repo access.

# `has_org_role?`

Checks if user has at least a given role.

# `hf_hub_download`

Downloads a file to the local HF cache and returns the path.

# `hf_hub_url`

Returns the download URL for a file.

# `hide_discussion_comment`

Hides a comment.

# `inspect_job`

Gets job status.

# `invite_org_member`

Invites an org member.

# `like`

Likes a repository on the Hub.

# `list_accepted_access_requests`

Lists accepted gated repo requests.

# `list_bucket_tree`

Lists bucket files.

# `list_buckets`

```elixir
@spec list_buckets(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists buckets.

# `list_collections`

```elixir
@spec list_collections(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists collections.

# `list_commits`

Lists commits for a repository.

# `list_datasets`

```elixir
@spec list_datasets(any()) :: Enumerable.t()
```

Lists datasets with full filter support (lazy stream).

# `list_discussions`

Lists discussions and PRs.

# `list_files`

Lists files in a repository.

# `list_inference_endpoints`

```elixir
@spec list_inference_endpoints(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists inference endpoints.

# `list_job_hardware`

Lists available hardware flavors.

# `list_jobs`

Lists jobs.

# `list_leaderboards`

```elixir
@spec list_leaderboards(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists leaderboards.

# `list_liked_repos`

```elixir
@spec list_liked_repos(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists repositories liked by a user.

# `list_metrics`

```elixir
@spec list_metrics(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists available metrics.

# `list_models`

```elixir
@spec list_models(any()) :: Enumerable.t()
```

Lists models with full filter support (lazy stream).

# `list_my_orgs`

```elixir
@spec list_my_orgs(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists orgs for the authenticated user.

# `list_org_members`

Lists org members.

# `list_papers`

```elixir
@spec list_papers(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists papers.

# `list_pending_access_requests`

Lists pending gated repo requests.

# `list_rejected_access_requests`

Lists rejected gated repo requests.

# `list_repo_refs`

Lists all branches and tags for a repository.

# `list_scheduled_jobs`

Lists scheduled jobs.

# `list_space_logs`

Gets logs from a Space.

# `list_space_secrets`

Lists Space secrets (keys only).

# `list_spaces`

```elixir
@spec list_spaces(any()) :: Enumerable.t()
```

Lists spaces (lazy stream).

# `list_user_followers`

Lists a user's followers.

# `list_user_following`

Lists users that a user follows.

# `list_webhooks`

```elixir
@spec list_webhooks(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Lists webhooks.

# `load_dduf_from_hub`

Downloads and opens a DDUF file from the Hub.

# `load_from_hub`

```elixir
@spec load_from_hub(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
```

Downloads a model from the Hub (equivalent to from_pretrained).

# `lora_config`

```elixir
@spec lora_config(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Builds a LoRA fine-tuning configuration.

# `merge_pull_request`

Merges a pull request.

# `model_benchmarks`

Gets model benchmarks.

# `model_info`

Gets detailed info about a model.

# `model_tags`

```elixir
@spec model_tags(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Returns all model tags.

# `move_bucket`

```elixir
@spec move_bucket(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Renames a bucket.

# `move_repo`

```elixir
@spec move_repo(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Moves or renames a repository.

# `my_org_role`

Returns user's role in an organization.

# `oauth_handle_redirect`

OAuth callback handler.

# `oauth_login_url`

```elixir
@spec oauth_login_url(any()) :: String.t()
```

OAuth login URL.

# `open_llm_leaderboard`

Returns Open LLM Leaderboard results.

# `org_info`

Gets org info.

# `paper_info`

Gets paper info.

# `parse_safetensors`

Parses safetensors metadata from a model repo.

# `pause_inference_endpoint`

Pauses an inference endpoint.

# `pause_space`

Pauses a Space.

# `push_eval_results`

Pushes eval results.

# `push_model_card`

```elixir
@spec push_model_card(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
```

Pushes a model card to the Hub.

# `push_to_hub`

```elixir
@spec push_to_hub(any(), any(), any()) :: {:ok, term()} | {:error, Exception.t()}
```

Pushes a model (weights + config) to a Hub repo.

# `read_dduf_file`

```elixir
@spec read_dduf_file(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Reads a DDUF file.

# `read_model_card`

Reads a model card.

# `reject_access_request`

Rejects a gated repo request.

# `remove_org_member`

Removes an org member.

# `rename_discussion`

Renames a discussion.

# `repo_exists?`

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

Checks if a repository exists.

# `repo_papers`

Gets papers associated with a repo.

# `request_space_hardware`

Requests hardware upgrade.

# `restart_space`

Restarts a Space.

# `resume_inference_endpoint`

Resumes an inference endpoint.

# `revoke_access`

Revokes repo access.

# `run_job`

```elixir
@spec run_job(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Runs a Docker job on HF infrastructure.

# `run_uv_job`

Runs a UV Python script.

# `scale_inference_endpoint_to_zero`

Scales endpoint to zero.

# `scan_cache`

```elixir
@spec scan_cache(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Scans the local HF cache.

# `search_datasets`

```elixir
@spec search_datasets(any()) :: Enumerable.t()
```

Searches datasets.

# `search_hub`

Full-text search across Hub content.

# `search_models`

```elixir
@spec search_models(any()) :: Enumerable.t()
```

Searches models with full filter support.

# `search_papers`

```elixir
@spec search_papers(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
```

Searches papers.

# `search_spaces`

```elixir
@spec search_spaces(any()) :: Enumerable.t()
```

Searches Spaces.

# `set_space_sleep_time`

Sets sleep time.

# `snapshot_download`

Downloads an entire repository to the local cache.

# `space_dev_mode`

Enables/disables dev mode.

# `space_info`

Gets info about a Space.

# `stream_audit_logs`

Streams audit log entries for an organization.

# `submit_to_leaderboard`

```elixir
@spec submit_to_leaderboard(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Submits to a leaderboard.

# `super_squash_history`

Squashes all commits in a branch into one.

# `tag_commit`

```elixir
@spec tag_commit(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
```

Tags a specific commit.

# `training_recipe`

Returns a pre-built fine-tuning recipe.

# `trending_models`

```elixir
@spec trending_models(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Returns trending models.

# `trending_spaces`

```elixir
@spec trending_spaces(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Returns trending Spaces.

# `unlike`

Unlikes a repository on the Hub.

# `update_collection`

Updates a collection.

# `update_collection_item`

Updates a collection item (position, note).

# `update_inference_endpoint`

Updates an inference endpoint.

# `update_repo_metadata`

Updates repo metadata.

# `update_repo_settings`

Updates repository settings (private, gated, etc.).

# `update_webhook`

Updates a webhook.

# `upload_bucket_file`

Uploads a file to a bucket.

# `upload_file`

Uploads a single file.

# `upload_files`

Uploads multiple files in a single commit.

# `upload_folder`

Uploads an entire local folder.

# `user_info`

Gets a user's profile.

# `wait_for_job`

Waits for a job to finish.

# `who_am_i`

```elixir
@spec who_am_i(any()) :: {:ok, term()} | {:error, Exception.t()}
```

Returns info about the authenticated user.

---

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