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

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")

# `item_type`

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

# `sort`

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

# `add_item`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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)

---

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