Add Collection API

[Wauplin]

This PR adds support fpr the Collection API (implements #1682).

EDIT: PR is ready for review. Tests are still failing but a server-side change is coming (https://github.com/huggingface/moon-landing/pull/7548)

Documentation:

• Guide
• Package reference
• HF-hub docs: incoming

Create/get/update/delete collection:

• get_collection
• create_collection: title, description, namespace, private
• update_collection_metadata: title, description, position, private, theme
• delete_collection

It does not include a way to list/search collections. We can do that in a later PR once it's fully supported server-side (currently only possible to list your own collections).

Add/update/remove item from collection:

• add_collection_item: item id, item type, note
• update_collection_item: note, position
• delete_collection_item

Usage

>>> from huggingface_hub import get_collection
>>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026")
>>> collection.title
'Recent models'
>>> len(collection.items)
37
>>> collection.items[0]
CollectionItem: {
    {'_id': '6507f6d5423b46492ee1413e',
    'id': 'TheBloke/TigerBot-70B-Chat-GPTQ',
    'author': 'TheBloke',
    'item_type': 'model',
    'lastModified': '2023-09-19T12:55:21.000Z',
    (...)
}}

>>> from huggingface_hub import create_collection

# Create collection
>>> collection = create_collection(
...     title="ICCV 2023",
...     description="Portfolio of models, papers and demos I presented at ICCV 2023",
... )

# Add collection with a note
>>> add_collection_item(
...     collection_slug="davanstrien/climate-64f99dc2a5067f6b65531bab",
...     item_id="datasets/climate_fever",
...     item_type="dataset"
...     note="This dataset adopts the FEVER methodology that consists of 1,535 real-world claims regarding climate-change collected on the internet."
... )

TODO

• merge moon-landing/7536 (internal)
• merge moon-landing/7538 (internal)
• merge moon-landing/7548 (internal)
• add unit test
• add Collection API to package reference (methods + classes)
• add guide about Collection API
• document public API in hf-docs (different PR)

[HuggingFaceDocBuilderDev]

The documentation is not available anymore as the PR was closed or merged.

[osanseviero]

nice find :D

[Wauplin]

Always try to highlight some cool stuff in the docs examples 🤗

[julien-c]

nice growth hack for Omar's profile:)

[LysandreJik]

cc @vwxyzjn who was wondering whether this was possible or not

[LysandreJik]

Clean implementation, a welcome addition!

Maybe we could also eventually add support for that in transformers/diffusers/etc or at least show in the docs how to add to a collection a fresh model uploaded using push_to_hub

[stevhliu]

Super nice guide! 💯

[Wauplin]

Thank you so much for the guide review @stevhliu ! ❤️ I've addressed all of your comments which is always a great improvement to the guides 🎉

[Wauplin]

Server-side PRs are not all merged and tests are green ✔️.

Still having a code quality error but it's been solved in #1693 (types-requests got updated) and in PR documentation which is being solved in huggingface/doc-builder#405. Both are not related to this PR.

So thanks @LysandreJik and @stevhliu for the reviews, I think we're good to merge now! 🎉 🚀

[HuggingFaceDocBuilderDev]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint.

[davanstrien]

Would adding a collection_url/url attribute to the Collection object make sense? I realise this can easily be got from the slug i.e. f"https:huggingface.co/collections/{collection.slug}" but maybe it's nice to make it easier for a user to quickly access that so they can check their collection via the Hub more quickly?

[Wauplin]

Would adding a collection_url/url attribute to the Collection object make sense? I realise this can easily be got from the slug i.e. f"https:huggingface.co/collections/{collection.slug}" but maybe it's nice to make it easier for a user to quickly access that so they can check their collection via the Hub more quickly?

Yes that makes a lot of sense for usability, thanks for the suggestion @davanstrien. I opened #1695 to add it.

[Wauplin]

Next huggingface_hub release is not yet planned. In the meantime it is possible to use the Collection API by installing the library from source:

pip install git+https://github.com/huggingface/huggingface_hub@main

EDIT: it's released! https://github.com/huggingface/huggingface_hub/releases/tag/v0.18.0

[julien-c]

maybe pin this as instruction in the GH issues and/or even in the README! i think many community members will be interested