[FEAT] hub integration with dataset and configuration (#5161)

This is an experimental WIP pr to get feedback on the approach. I've
migrated the code out of the v1 argilla client, and reimplemented for v2
changes. It would be great to get feedback on issues like this:

- testing with a mocked hub api.
- dealing with responses across argilla servers and mismatched user_ids.
- dealing with dependencies like `huggingface_hub`. I like the decorator
used in the v1 client.

Here's a dataset that I pushed. Still uses default readme from v1:

https://huggingface.co/datasets/burtenshaw/test-argilla-dataset

To test this implementation do:

```python
import uuid

from datetime import datetime

import argilla as rg

client = rg.Argilla(api_key="owner.apikey")
workspace = client.workspaces[0]
mock_dataset_name = (
    f"test_add_record_with_suggestions {datetime.now().strftime('%Y%m%d%H%M%S')}"
)
mock_data = [
    {
        "text": "Hello World, how are you?",
        "label": "positive",
        "id": uuid.uuid4(),
        "comment": "I'm doing great, thank you!",
        "topics": ["topic1", "topic2"],
        "topics.score": [0.9, 0.8],
    },
    {
        "text": "Hello World, how are you?",
        "label": "negative",
        "id": uuid.uuid4(),
        "comment": "I'm doing great, thank you!",
        "topics": ["topic3"],
        "topics.score": [0.9],
    },
    {
        "text": "Hello World, how are you?",
        "label": "positive",
        "id": uuid.uuid4(),
        "comment": "I'm doing great, thank you!",
        "comment_score": 0.9,  # This field will be ignored because it is not in the mapping
        "rating": 1,
        "topics": ["topic1", "topic2", "topic3"],
        "topics.score": [0.9, 0.8, 0.7],
        "ranking": ["label1", "label2", "label3"],
        "span": [
            {
                "start": 0,
                "end": 5,
                "label": "label1",
            },
            {
                "start": 6,
                "end": 11,
                "label": "label2",
            },
            {
                "start": 12,
                "end": 17,
                "label": "label3",
            },
        ],
        "vector": [1, 2, 3],
    },
]
settings = rg.Settings(
    fields=[
        rg.TextField(name="text"),
    ],
    questions=[
        rg.LabelQuestion(name="label", labels=["positive", "negative"]),
        rg.RatingQuestion(name="rating", values=[1, 2, 3, 4, 5]),
        rg.RankingQuestion(name="ranking", values=["label1", "label2", "label3"]),
        rg.TextQuestion(name="comment", use_markdown=False),
        rg.MultiLabelQuestion(
            name="topics",
            labels=["topic1", "topic2", "topic3"],
            labels_order="suggestion",
        ),
        rg.SpanQuestion(
            name="span", labels=["label1", "label2", "label3"], field="text"
        ),
    ],
    metadata=[
        rg.FloatMetadataProperty(name="comment_score"),
    ],
    vectors=[
        rg.VectorField(name="vector", dimensions=3),
    ],
)
dataset = rg.Dataset(
    name=mock_dataset_name,
    settings=settings,
    client=client,
)
dataset.create()
dataset.records.log(
    mock_data,
    mapping={
        "comment": "comment.suggestion",
        "comment_score": "comment.suggestion.score",  # This field will be ignored because it is not in the mapping
        "topics": "topics.suggestion",
        "topics.score": "topics.suggestion.score",
        "label": "label.response",
        "span": "span",
    },
)

dataset.to_hub(repo_id="burtenshaw/test-argilla-dataset")


pulled_dataset = from_huggingface("burtenshaw/test-argilla-dataset")
```

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Paco Aranda <[email protected]>
Co-authored-by: David Berenstein <[email protected]>
Co-authored-by: Daniel Vila Suero <[email protected]>
Co-authored-by: Lucain <[email protected]>

Author: 6 people

argilla/docs/how_to_guides/import_export.md

@@ -0,0 +1,179 @@
+---
+description: In this section, we will provide a step-by-step guide to show how to import and export datasets to Python, local disk, or the Hugging Face Hub
+---
+
+# Importing and exporting datasets and records
+
+This guide provides an overview of how to import and export your dataset or its records to Python, your local disk, or the Hugging Face Hub.
+
+In Argilla, you can import/export two main components of a dataset:
+- The dataset's complete configuration defined in `rg.Settings`. This is useful if your want to share your feedback task or restore it later in Argilla.
+- The records stored in the dataset, including `Metadata`, `Vectors`, `Suggestions`, and `Responses`. This is useful if you want to use your dataset's records outside of Argilla.
+
+Check the [Dataset - Python Reference](../reference/argilla/datasets/dataset.md) to see the attributes, arguments, and methods of the export `Dataset` class in detail.
+
+To import records to a dataset, used the `rg.Datasets.records.log` method. Their is a guide on how to do this in the [Record - Python Reference](record.md).
+
+## Import and Export an `rg.Dataset` from Argilla
+
+First, we will go through exporting a complete dataset from Argilla. This includes the dataset's setting and records. All of these methods use the `rg.Dataset.from_*` and `rg.Dataset.to_*` methods.
+
+### Push an Argilla dataset to the Hugging Face Hub
+
+You can push a dataset from Argilla to the Hugging Face Hub. This is useful if you want to share your dataset with the community or version control it. You can push the dataset to the Hugging Face Hub using the `rg.Dataset.to_hub` method.
+
+```python
+import argilla as rg
+
+client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
+dataset = client.datasets(name="my_dataset")
+dataset.to_hub(repo_id="<repo_id>")
+```
+
+!!! note "With or without records"
+    The example above will push the dataset's `Settings` and records to the hub. If you only want to push the dataset's configuration, you can set the `with_records` parameter to `False`. This is useful if you're just interested in a specific dataset template or you want to make changes in the dataset settings and/or records.
+
+    ```python
+    dataset.to_hub(repo_id="<repo_id>", with_records=False)
+    ```
+
+
+### Pull an Argilla dataset from the Hugging Face Hub
+
+You can pull a dataset from the Hugging Face Hub to Argilla. This is useful if you want to restore a dataset and its configuration. You can pull the dataset from the Hugging Face Hub using the `rg.Dataset.from_hub` method.
+
+```python
+
+import argilla as rg
+
+client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
+dataset = rg.Dataset.from_hub(repo_id="<repo_id>")
+```
+
+The `rg.Dataset.from_hub` method loads the configuration and records from the dataset repo. If you only want to load records, you can pass a `datasets.Dataset` object to the `rg.Dataset.log` method. This enables you to configure your own dataset and reuse existing Hub datasets. See the [guide on records](record.md) for more information.
+
+!!! note "With or without records"
+
+    The example above will pull the dataset's `Settings` and records from the hub. If you only want to pull the dataset's configuration, you can set the `with_records` parameter to `False`. This is useful if you're just interested in a specific dataset template or you want to make changes in the dataset settings and/or records.
+
+    ```python
+    dataset = rg.Dataset.from_hub(repo_id="<repo_id>", with_records=False)
+    ```
+
+    With the dataset's configuration you could then make changes to the dataset. For example, you could adapt the dataset's settings for a different task:
+
+    ```python
+    dataset.settings.questions = [rg.TextQuestion(name="answer")]
+    ```
+
+    You could then log the dataset's records using the `load_dataset` method of the `datasets` package and pass the dataset to the `rg.Dataset.log` method.
+
+    ```python
+    hf_dataset = load_dataset("<repo_id>")
+    dataset.log(hf_dataset)
+    ```
+
+
+
+### Saving an Argilla dataset to local disk
+
+You can save a dataset from Argilla to your local disk. This is useful if you want to back up your dataset. You can use the `rg.Dataset.to_disk` method.
+
+```python
+import argilla as rg
+
+client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
+dataset = client.datasets(name="my_dataset", workspace=workspace)
+
+dataset.to_disk(path="path/to/dataset")
+```
+
+This will save the dataset's configuration and records to the specified path. If you only want to save the dataset's configuration, you can set the `with_records` parameter to `False`.
+
+```python
+dataset.to_disk(path="path/to/dataset", with_records=False)
+```
+
+### Loading an Argilla dataset from local disk
+
+You can load a dataset from your local disk to Argilla. This is useful if you want to restore a dataset's configuration. You can use the `rg.Dataset.from_disk` method.
+
+```python
+import argilla as rg
+
+dataset = rg.Dataset.from_disk(path="path/to/dataset")
+```
+
+!!! note "Directing the dataset to a workspace and name"
+    You can also specify the workspace and name of the dataset when loading it from the disk.
+
+    ```python
+    dataset = rg.Dataset.from_disk(path="path/to/dataset", target_workspace=workspace, target_name="my_dataset")
+    ```
+
+## Export only records from Argilla Datasets
+
+The records alone can be exported from a dataset in Argilla.  This is useful if you want to process the records in Python, export them to a different platform, or use them in model training. All of these methods use the `rg.Dataset.records` attribute.
+
+The records can be exported as a dictionary, a list of dictionaries, or to a `Dataset` of the `datasets` package.
+
+
+=== "To the `datasets` package"
+
+
+    Records can be exported from `Dataset.records` to the `datasets` package. The `to_dataset` method can be used to export records to the `datasets` package. You can specify the name of the dataset and the split to export the records.
+
+    ```python
+    import argilla as rg
+
+    client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
+    dataset = client.datasets(name="my_dataset")
+
+    # Export records as a dictionary
+    exported_ds = dataset.records.to_datasets()
+    ```
+
+=== "To a Python dictionary"
+
+    Records can be exported from `Dataset.records` as a dictionary. The `to_dict` method can be used to export records as a dictionary. You can specify the orientation of the dictionary output. You can also decide if to flatten or not the dictionary.
+
+    ```python
+    import argilla as rg
+
+    client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
+    dataset = client.datasets(name="my_dataset")
+
+    # Export records as a dictionary
+    exported_records = dataset.records.to_dict()
+    # {'fields': [{'text': 'Hello'},{'text': 'World'}], suggestions': [{'label': {'value': 'positive'}}, {'label': {'value': 'negative'}}]
+
+    # Export records as a dictionary with orient=index
+    exported_records = dataset.records.to_dict(orient="index")
+    # {"uuid": {'fields': {'text': 'Hello'}, 'suggestions': {'label': {'value': 'positive'}}}, {"uuid": {'fields': {'text': 'World'}, 'suggestions': {'label': {'value': 'negative'}}},
+
+    # Export records as a dictionary with flatten=false
+    exported_records = dataset.records.to_dict(flatten=True)
+    # {"text": ["Hello", "World"], "label.suggestion": ["greeting", "greeting"]}
+    ```
+
+=== "To a python list"
+
+    Records can be exported from `Dataset.records` as a list of dictionaries. The `to_list` method can be used to export records as a list of dictionaries. You can decide if to flatten it or not.
+
+    ```python
+    import argilla as rg
+
+    client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
+
+    workspace = client.workspaces("my_workspace")
+
+    dataset = client.datasets(name="my_dataset", workspace=workspace)
+
+    # Export records as a list of dictionaries
+    exported_records = dataset.records.to_list()
+    # [{'fields': {'text': 'Hello'}, 'suggestion': {'label': {value: 'greeting'}}}, {'fields': {'text': 'World'}, 'suggestion': {'label': {value: 'greeting'}}}]
+
+    # Export records as a list of dictionaries with flatten=False
+    exported_records = dataset.records.to_list(flatten=True)
+    # [{"text": "Hello", "label": "greeting"}, {"text": "World", "label": "greeting"}]
+    ```

argilla/docs/how_to_guides/index.md

@@ -43,13 +43,21 @@ These guides provide step-by-step instructions for common scenarios, including d
 
     [:octicons-arrow-right-24: How-to guide](record.md)
 
--   __Query, filter and export records__
+-   __Query and filter a dataset__
 
     ---
 
-    Learn how to query and filter a `Dataset` and export their `Records`.
+    Learn how to query and filter a `Dataset`.
 
-    [:octicons-arrow-right-24: How-to guide](query_export.md)
+    [:octicons-arrow-right-24: How-to guide](query.md)
+
+-   __Importing and exporting datasets and records__
+
+    ---
+
+    Learn how to export your dataset or its records to Python, your local disk, or the Hugging face Hub.
+
+    [:octicons-arrow-right-24: How-to guide](import_export.md)
 
 </div>
 

argilla/docs/how_to_guides/query_export.md renamed to argilla/docs/how_to_guides/query.md

@@ -2,9 +2,9 @@
 description: In this section, we will provide a step-by-step guide to show how to filter and query a dataset.
 ---
 
-# Query, filter, and export records
+# Query and filter records
 
-This guide provides an overview of how to query and filter a dataset in Argilla and export records.
+This guide provides an overview of how to query and filter a dataset in Argilla.
 
 You can search for records in your dataset by **querying** or **filtering**. The query focuses on the content of the text field, while the filter is used to filter the records based on conditions. You can use them independently or combine multiple filters to create complex search queries. You can also export records from a dataset either as a single dictionary or a list of dictionaries.
 
@@ -170,53 +170,3 @@ queried_filtered_records = list(dataset.records(
 )
 )
 ```
-
-## Export records to a dictionary
-
-Records can be exported from `Dataset.records` as a dictionary. The `to_dict` method can be used to export records as a dictionary. You can specify the orientation of the dictionary output. You can also decide if to flatten or not the dictionary.
-
-=== "
-
-```python
-import argilla as rg
-
-client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
-
-workspace = client.workspaces("my_workspace")
-
-dataset = client.datasets(name="my_dataset", workspace=workspace)
-
-# Export records as a dictionary
-exported_records = dataset.records.to_dict()
-# {'fields': [{'text': 'Hello'},{'text': 'World'}], suggestions': [{'label': {'value': 'positive'}}, {'label': {'value': 'negative'}}]
-
-# Export records as a dictionary with orient=index
-exported_records = dataset.records.to_dict(orient="index")
-# {"uuid": {'fields': {'text': 'Hello'}, 'suggestions': {'label': {'value': 'positive'}}}, {"uuid": {'fields': {'text': 'World'}, 'suggestions': {'label': {'value': 'negative'}}},
-
-# Export records as a dictionary with flatten=false
-exported_records = dataset.records.to_dict(flatten=True)
-# {"text": ["Hello", "World"], "label.suggestion": ["greeting", "greeting"]}
-```
-
-## Export records to a list
-
-Records can be exported from `Dataset.records` as a list of dictionaries. The `to_list` method can be used to export records as a list of dictionaries. You can decide if to flatten it or not.
-
-```python
-import argilla as rg
-
-client = rg.Argilla(api_url="<api_url>", api_key="<api_key>")
-
-workspace = client.workspaces("my_workspace")
-
-dataset = client.datasets(name="my_dataset", workspace=workspace)
-
-# Export records as a list of dictionaries
-exported_records = dataset.records.to_list()
-# [{'fields': {'text': 'Hello'}, 'suggestion': {'label': {value: 'greeting'}}}, {'fields': {'text': 'World'}, 'suggestion': {'label': {value: 'greeting'}}}]
-
-# Export records as a list of dictionaries with flatten=False
-exported_records = dataset.records.to_list(flatten=True)
-# [{"text": "Hello", "label": "greeting"}, {"text": "World", "label": "greeting"}]
-```

argilla/docs/how_to_guides/record.md

@@ -485,7 +485,7 @@ dataset.records.delete(records=records_to_delete)
 !!! tip "Delete records based on a query"
     It can be very useful to avoid eliminating records with responses.
 
-    > For more information about the query syntax, check this [how-to guide](query_export.md).
+    > For more information about the query syntax, check this [how-to guide](query.md).
 
     ```python
     status_filter = rg.Query(

argilla/docs/reference/argilla/client.md

@@ -44,10 +44,9 @@ for dataset in my_workspace.datasets:
 
 ---
 
-## Class Reference
-
-### `rg.Argilla`
+##  `rg.Argilla`
 
 ::: src.argilla.client.Argilla
     options:
         heading_level: 3
+        show_root_toc_entry: false

argilla/docs/reference/argilla/datasets/dataset_records.md

@@ -215,10 +215,9 @@ Check out the [`rg.Record`](../records/records.md) class reference for more info
 
 ---
 
-## Class Reference
-
-### `rg.Dataset.records`
+##  `rg.Dataset.records`
 
 ::: src.argilla.records._dataset_records.DatasetRecords
     options:
-        heading_level: 3
+        heading_level: 3
+        show_root_toc_entry: false

argilla/docs/reference/argilla/datasets/datasets.md

@@ -39,10 +39,21 @@ dataset = client.datasets("my_dataset")
 
 ---
 
-## Class Reference
-
-### `rg.Dataset`
+##  `rg.Dataset`
 
 ::: src.argilla.datasets._resource.Dataset
     options:
-        heading_level: 3
+        heading_level: 3
+        show_root_toc_entry: false
+
+::: src.argilla.datasets._export._disk.DiskImportExportMixin
+    options:
+        heading_level: 3
+        show_root_heading: false
+        show_root_toc_entry: false
+
+::: src.argilla.datasets._export._hub.HubImportExportMixin
+    options:
+        heading_level: 3
+        show_root_heading: false
+        show_root_toc_entry: false

argilla/docs/reference/argilla/records/records.md

@@ -52,10 +52,9 @@ For changes to take effect, the user must call the `update` method on the `Datas
 
 ---
 
-## Class Reference
-
-### `rg.Record`
+## `rg.Record`
 
 ::: src.argilla.records._resource.Record
     options:
-        heading_level: 3
+        heading_level: 3
+        show_root_toc_entry: false

argilla/docs/reference/argilla/records/responses.md

@@ -67,10 +67,9 @@ for record in dataset.records:
 
 ---
 
-## Class Reference
-
-### `rg.Response`
+## `rg.Response`
 
 ::: src.argilla.responses.Response
     options:
-        heading_level: 3
+        heading_level: 3
+        show_root_toc_entry: false

argilla/docs/reference/argilla/records/suggestions.md

@@ -82,10 +82,9 @@ for record in dataset.records(with_suggestions=True):
 
 ---
 
-## Class Reference
-
-### `rg.Suggestion`
+## `rg.Suggestion`
 
 ::: src.argilla.suggestions.Suggestion
     options:
-        heading_level: 3
+        heading_level: 3
+        show_root_toc_entry: false