[FEATURE] pass dataset Settings to from_hub method (#5418)

# Description
<!-- Please include a summary of the changes and the related issue.
Please also include relevant motivation and context. List any
dependencies that are required for this change. -->

This PR adds a settings parameter to the `from_hub` method so that it is
compatible with datasets that do not have a `.argilla` directory.

**Type of change**
<!-- Please delete options that are not relevant. Remember to title the
PR according to the type of change -->

- Bug fix (non-breaking change which fixes an issue)
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- Refactor (change restructuring the codebase without changing
functionality)
- Improvement (change adding some improvement to an existing
functionality)
- Documentation update

**How Has This Been Tested**
<!-- Please add some reference about how your feature has been tested.
-->

**Checklist**
<!-- Please go over the list and make sure you've taken everything into
account -->

- I added relevant documentation
- I followed the style guidelines of this project
- I did a self-review of my code
- I made corresponding changes to the documentation
- I confirm My changes generate no new warnings
- I have added tests that prove my fix is effective or that my feature
works
- I have added relevant notes to the CHANGELOG.md file (See
https://keepachangelog.com/)

---------

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

Author: 3 people

argilla/src/argilla/datasets/_export/_hub.py

@@ -19,6 +19,9 @@
 from typing import TYPE_CHECKING, Any, Optional, Type, Union
 from uuid import UUID
 
+from argilla._exceptions._api import UnprocessableEntityError
+from argilla._exceptions._records import RecordsIngestionError
+from argilla._exceptions._settings import SettingsError
 from datasets.data_files import EmptyDatasetError
 
 from argilla.datasets._export._disk import DiskImportExportMixin
@@ -28,7 +31,7 @@
 if TYPE_CHECKING:
     from datasets import Dataset as HFDataset
 
-    from argilla import Argilla, Dataset, Workspace
+    from argilla import Argilla, Dataset, Workspace, Settings
 
 
 class HubImportExportMixin(DiskImportExportMixin):
@@ -110,6 +113,7 @@ def from_hub(
         workspace: Optional[Union["Workspace", str]] = None,
         client: Optional["Argilla"] = None,
         with_records: bool = True,
+        settings: Optional["Settings"] = None,
         **kwargs: Any,
     ):
         """Loads a `Dataset` from the Hugging Face Hub.
@@ -128,17 +132,21 @@ def from_hub(
         from datasets import Dataset, DatasetDict, load_dataset
         from huggingface_hub import snapshot_download
 
-        # download both files in parallel
-        folder_path = snapshot_download(
-            repo_id=repo_id,
-            repo_type="dataset",
-            allow_patterns=cls._DEFAULT_CONFIGURATION_FILES,
-            token=kwargs.get("token"),
-        )
+        if settings is not None:
+            dataset = cls(name=name, settings=settings)
+            dataset.create()
+        else:
+            # download configuration files from the hub
+            folder_path = snapshot_download(
+                repo_id=repo_id,
+                repo_type="dataset",
+                allow_patterns=cls._DEFAULT_CONFIGURATION_FILES,
+                token=kwargs.get("token"),
+            )
 
-        dataset = cls.from_disk(
-            path=folder_path, workspace=workspace, name=name, client=client, with_records=with_records
-        )
+            dataset = cls.from_disk(
+                path=folder_path, workspace=workspace, name=name, client=client, with_records=with_records
+            )
 
         if with_records:
             try:
@@ -150,8 +158,23 @@ def from_hub(
                             f" are: {', '.join(hf_dataset.keys())}."
                         )
                     hf_dataset: Dataset = hf_dataset[list(hf_dataset.keys())[0]]
-
-                cls._log_dataset_records(hf_dataset=hf_dataset, dataset=dataset)
+                for feature in hf_dataset.features:
+                    if feature not in dataset.settings.fields or feature not in dataset.settings.questions:
+                        warnings.warn(
+                            message=f"Feature {feature} in Hugging Face dataset is not defined in dataset settings."
+                        )
+                        warnings.warn(
+                            message=f"Available fields: {dataset.settings.fields}. Available questions: {dataset.settings.questions}."
+                        )
+                try:
+                    cls._log_dataset_records(hf_dataset=hf_dataset, dataset=dataset)
+                except (RecordsIngestionError, UnprocessableEntityError) as e:
+                    if settings is not None:
+                        raise SettingsError(
+                            message=f"Failed to load records from Hugging Face dataset. Defined settings do not match dataset schema {hf_dataset.features}"
+                        ) from e
+                    else:
+                        raise e
             except EmptyDatasetError:
                 warnings.warn(
                     message="Trying to load a dataset `with_records=True` but dataset does not contain any records.",

argilla/tests/integration/test_export_dataset.py

@@ -22,7 +22,7 @@
 
 import argilla as rg
 import pytest
-from argilla._exceptions import ConflictError
+from argilla._exceptions import ConflictError, SettingsError
 from huggingface_hub.utils._errors import BadRequestError, FileMetadataError, HfHubHTTPError
 
 _RETRIES = 5
@@ -202,3 +202,81 @@ def test_import_dataset_from_hub(
 
         assert new_dataset.settings.fields[0].name == "text"
         assert new_dataset.settings.questions[0].name == "label"
+
+    @pytest.mark.parametrize("with_records_import", [True, False])
+    def test_import_dataset_from_hub_using_settings(
+        self,
+        token: str,
+        dataset: rg.Dataset,
+        client,
+        mock_data: List[dict[str, Any]],
+        with_records_export: bool,
+        with_records_import: bool,
+    ):
+        repo_id = (
+            f"argilla-internal-testing/test_import_dataset_from_hub_using_settings_with_records{with_records_export}"
+        )
+        dataset.records.log(records=mock_data)
+
+        dataset.to_hub(repo_id=repo_id, with_records=with_records_export, token=token)
+        settings = rg.Settings(
+            fields=[
+                rg.TextField(name="text"),
+            ],
+            questions=[
+                rg.LabelQuestion(name="label", labels=["positive", "negative"]),
+                rg.LabelQuestion(name="extra_label", labels=["extra_positive", "extra_negative"]),
+            ],
+        )
+        if with_records_import and not with_records_export:
+            with pytest.warns(
+                expected_warning=UserWarning,
+                match="Trying to load a dataset `with_records=True` but dataset does not contain any records.",
+            ):
+                new_dataset = rg.Dataset.from_hub(
+                    repo_id=repo_id, client=client, with_records=with_records_import, token=token, settings=settings
+                )
+        else:
+            new_dataset = rg.Dataset.from_hub(
+                repo_id=repo_id, client=client, with_records=with_records_import, token=token, settings=settings
+            )
+
+        if with_records_import and with_records_export:
+            for i, record in enumerate(new_dataset.records(with_suggestions=True)):
+                assert record.fields["text"] == mock_data[i]["text"]
+                assert record.suggestions["label"].value == mock_data[i]["label"]
+        else:
+            assert len(new_dataset.records.to_list()) == 0
+
+        assert new_dataset.settings.fields[0].name == "text"
+        assert new_dataset.settings.questions[0].name == "label"
+        assert new_dataset.settings.questions[1].name == "extra_label"
+        assert len(new_dataset.settings.questions[1].labels) == 2
+        assert new_dataset.settings.questions[1].labels[0] == "extra_positive"
+        assert new_dataset.settings.questions[1].labels[1] == "extra_negative"
+
+    def test_import_dataset_from_hub_using_wrong_settings(
+        self,
+        token: str,
+        dataset: rg.Dataset,
+        client,
+        mock_data: List[dict[str, Any]],
+        with_records_export: bool,
+    ):
+        repo_id = f"argilla-internal-testing/test_import_dataset_from_hub_using_wrong_settings_with_records_{with_records_export}"
+        dataset.records.log(records=mock_data)
+
+        dataset.to_hub(repo_id=repo_id, with_records=with_records_export, token=token)
+        settings = rg.Settings(
+            fields=[
+                rg.TextField(name="text"),
+            ],
+            questions=[
+                rg.RatingQuestion(name="label", values=[1, 2, 3, 4, 5]),
+            ],
+        )
+        if with_records_export:
+            with pytest.raises(SettingsError):
+                rg.Dataset.from_hub(repo_id=repo_id, client=client, token=token, settings=settings)
+        else:
+            rg.Dataset.from_hub(repo_id=repo_id, client=client, token=token, settings=settings)