HfHub.Collections (HfHub v0.2.0)

Collections API for organizing models, datasets, and spaces on HuggingFace Hub.

Collections enable users to curate lists of repositories and papers.

Examples

# List all collections
{:ok, collections} = HfHub.Collections.list()

# List collections by owner
{:ok, collections} = HfHub.Collections.list(owner: "huggingface")

# Get a specific collection
{:ok, collection} = HfHub.Collections.get("user/my-llm-collection-123abc")

# Create a new collection
{:ok, collection} = HfHub.Collections.create("My LLM Collection",
  description: "Best open-source LLMs", token: "hf_xxx")

# Add an item to a collection
{:ok, item} = HfHub.Collections.add_item("user/collection-123",
  "bert-base-uncased", :model, note: "Best BERT model")

Summary

Types

item_type()

sort()

Functions

add_item(slug, item_id, item_type, opts \\ [])

Adds an item to a collection.

create(title, opts \\ [])

Creates a new collection.

delete(slug, opts \\ [])

Deletes a collection.

delete_item(slug, item_object_id, opts \\ [])

Removes an item from a collection.

get(slug, opts \\ [])

Gets a collection by slug.

list(opts \\ [])

Lists collections with optional filters.

update(slug, opts \\ [])

Updates collection metadata.

update_item(slug, item_object_id, opts \\ [])

Updates a collection item.

Types

item_type()

@type item_type() :: :model | :dataset | :space | :paper

sort()

@type sort() :: :last_modified | :trending | :upvotes

Functions

add_item(slug, item_id, item_type, opts \\ [])

@spec add_item(String.t(), String.t(), item_type(), keyword()) ::
  {:ok, HfHub.Collections.CollectionItem.t()} | {:error, term()}

Adds an item to a collection.

Arguments

slug - Collection slug
item_id - Item identifier (e.g., "bert-base-uncased")
item_type - Type of item (:model, :dataset, :space, or :paper)

Options

:note - Optional note about the item
:exists_ok - Don't error if item already in collection (default: false)
:token - Authentication token (required)

Examples

{:ok, item} = HfHub.Collections.add_item("user/collection-123",
  "bert-base-uncased", :model, note: "Best BERT model")

{:ok, item} = HfHub.Collections.add_item("user/collection-123",
  "squad", :dataset)

create(title, opts \\ [])

@spec create(
  String.t(),
  keyword()
) :: {:ok, HfHub.Collections.Collection.t()} | {:error, term()}

Creates a new collection.

Options

:namespace - Organization namespace (default: current user)
:description - Collection description
:private - Make collection private (default: false)
:exists_ok - Don't error if collection exists (default: false)
:token - Authentication token (required)

Examples

{:ok, collection} = HfHub.Collections.create("My LLM Collection",
  description: "Best open-source LLMs", token: "hf_xxx")

{:ok, collection} = HfHub.Collections.create("Private Collection",
  private: true, namespace: "my-org", token: "hf_xxx")

delete(slug, opts \\ [])

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

Deletes a collection.

Options

:missing_ok - Don't error if collection doesn't exist (default: false)
:token - Authentication token (required)

Examples

:ok = HfHub.Collections.delete("user/my-collection-123")
:ok = HfHub.Collections.delete("user/maybe-exists", missing_ok: true)

delete_item(slug, item_object_id, opts \\ [])

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

Removes an item from a collection.

Options

:missing_ok - Don't error if item doesn't exist (default: false)
:token - Authentication token (required)

Examples

:ok = HfHub.Collections.delete_item("user/collection-123", "item-object-id")

get(slug, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, HfHub.Collections.Collection.t()} | {:error, term()}

Gets a collection by slug.

Options

:token - Authentication token

Examples

{:ok, collection} = HfHub.Collections.get("user/my-llm-collection-123abc")

list(opts \\ [])

@spec list(keyword()) :: {:ok, [HfHub.Collections.Collection.t()]} | {:error, term()}

Lists collections with optional filters.

Options

:owner - Filter by owner username
:item - Filter by item (e.g., "bert-base-uncased")
:sort - Sort by :last_modified, :trending, or :upvotes
:token - Authentication token

Examples

{:ok, collections} = HfHub.Collections.list()
{:ok, collections} = HfHub.Collections.list(owner: "huggingface")
{:ok, collections} = HfHub.Collections.list(sort: :trending)

update(slug, opts \\ [])

@spec update(
  String.t(),
  keyword()
) :: {:ok, HfHub.Collections.Collection.t()} | {:error, term()}

Updates collection metadata.

Options

:title - New title
:description - New description
:private - Change visibility
:position - Reorder position
:theme - Collection theme
:token - Authentication token (required)

Examples

{:ok, collection} = HfHub.Collections.update("user/my-collection-123",
  title: "Updated Title", description: "New description")

update_item(slug, item_object_id, opts \\ [])

@spec update_item(String.t(), String.t(), keyword()) ::
  {:ok, HfHub.Collections.CollectionItem.t()} | {:error, term()}

Updates a collection item.

Options

:note - New note for the item
:position - New position in the collection
:token - Authentication token (required)

Examples

{:ok, item} = HfHub.Collections.update_item("user/collection-123", "item-object-id",
  note: "Updated note", position: 0)