Merge pull request #756 from superannotateai/develop

Develop

Author: VaghinakDev

.gitignore

@@ -54,6 +54,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+tests/tmp_test.py
 
 # Translations
 *.mo

CHANGELOG.rst

@@ -6,8 +6,23 @@ History
 
 All release highlights of this project will be documented in this file.
 
+
+4.4.31 - Feb 27, 2025
+_____________________
+
+**Added**
+
+    - Guide for Converting CSV and JSONL Formats.
+    - New SDK Functionality Table.
+
+**Updated**
+
+    - ``SAClient.attach_items_from_integrated_storage`` now supports Databricks integration, enabling efficient
+        data fetching and mapping from Databricks into SuperAnnotate.
+
 4.4.30 - Feb 13, 2025
 _____________________
+
 **Added**
 
     - ``SAClient.list_users`` method lists contributors with optional custom field filtering.

docs/source/api_reference/api_team.rst

@@ -10,3 +10,5 @@ Team
 .. automethod:: superannotate.SAClient.get_user_metadata
 .. automethod:: superannotate.SAClient.set_user_custom_field
 .. automethod:: superannotate.SAClient.list_users
+.. automethod:: superannotate.SAClient.pause_user_activity
+.. automethod:: superannotate.SAClient.resume_user_activity

src/superannotate/__init__.py

@@ -3,7 +3,7 @@
 import sys
 
 
-__version__ = "4.4.31dev1"
+__version__ = "4.4.31dev2"
 
 os.environ.update({"sa_version": __version__})
 sys.path.append(os.path.split(os.path.realpath(__file__))[0])

src/superannotate/lib/app/interface/sdk_interface.py

@@ -461,6 +461,16 @@ def list_users(self, *, include: List[Literal["custom_fields"]] = None, **filter
     def pause_user_activity(
         self, pk: Union[int, str], projects: Union[List[int], List[str], Literal["*"]]
     ):
+        """
+        Block the team contributor from requesting items from the projects.
+
+        :param pk: The email address or user ID of the team contributor.
+        :type pk: str or int
+
+        :param projects: A list of project names or IDs from which the user should be blocked.
+                        The special value "*" means block access to all projects
+        :type projects: Union[List[int], List[str], Literal["*"]]
+        """
         user = self.controller.work_management.get_user_metadata(pk=pk)
         if user.role is not WMUserTypeEnum.Contributor:
             raise AppException("User must have a contributor role to pause activity.")
@@ -474,6 +484,16 @@ def pause_user_activity(
     def resume_user_activity(
         self, pk: Union[int, str], projects: Union[List[int], List[str], Literal["*"]]
     ):
+        """
+        Resume the team contributor from requesting items from the projects.
+
+        :param pk: The email address or user ID of the team contributor.
+        :type pk: str or int
+
+        :param projects: A list of project names or IDs from which the user should be resumed.
+                        The special value "*" means resume access to all projects
+        :type projects: Union[List[int], List[str], Literal["*"]]
+        """
         user = self.controller.work_management.get_user_metadata(pk=pk)
         if user.role is not WMUserTypeEnum.Contributor:
             raise AppException("User must have a contributor role to resume activity.")
@@ -2919,32 +2939,80 @@ def attach_items_from_integrated_storage(
         project: NotEmptyStr,
         integration: Union[NotEmptyStr, IntegrationEntity],
         folder_path: Optional[NotEmptyStr] = None,
+        *,
+        query: Optional[NotEmptyStr] = None,
+        item_name_column: Optional[NotEmptyStr] = None,
+        custom_item_name: Optional[NotEmptyStr] = None,
+        component_mapping: Optional[Dict[str, str]] = None,
     ):
-        """Link images from integrated external storage to SuperAnnotate.
+        """Link images from integrated external storage to SuperAnnotate from AWS, GCP, Azure, Databricks.
 
         :param project: project name or folder path where items should be attached (e.g., “project1/folder1”).
         :type project: str
 
-        :param integration:  existing integration name or metadata dict to pull items from.
-         Mandatory keys in integration metadata’s dict is “name”.
+        :param integration: The existing integration name or metadata dict to pull items from.
+            Mandatory keys in integration metadata’s dict is “name”.
         :type integration: str or dict
 
         :param folder_path: Points to an exact folder/directory within given storage.
-         If None, items     are fetched from the root directory.
+            If None, items     are fetched from the root directory.
         :type folder_path: str
+
+        :param query: (Only for Databricks). The SQL query to retrieve specific columns from Databricks.
+            If provided, the function will execute the query and use the results for mapping and uploading.
+        :type query: Optional[str]
+
+        :param item_name_column: (Only for Databricks). The column name from the SQL query whose values
+            will be used as item names. If this is provided, custom_item_name cannot be used.
+            The column must exist in the query result.
+        :type item_name_column: Optional[str]
+
+        :param custom_item_name: (Only for Databricks). A manually defined prefix for item names.
+            A random 10-character suffix will be appended to ensure uniqueness.
+            If this is provided, item_name_column cannot be used.
+        :type custom_item_name: Optional[str]
+
+        :param component_mapping: (Only for Databricks). A dictionary mapping Databricks
+            columns to SuperAnnotate component IDs.
+        :type component_mapping: Optional[dict]
+
+
+        Request Example:
+        ::
+
+            client.attach_items_from_integrated_storage(
+                project="project_name",
+                integration="databricks_integration",
+                query="SELECT * FROM integration_data LIMIT 10",
+                item_name_column="prompt",
+                component_mapping={
+                    "category": "_item_category",
+                    "prompt_id": "id",
+                    "prompt": "prompt"
+                }
+            )
+
         """
         project, folder = self.controller.get_project_folder_by_path(project)
         _integration = None
         if isinstance(integration, str):
             integration = IntegrationEntity(name=integration)
         for i in self.controller.integrations.list().data:
-            if integration.name == i.name:
+            if integration.name.lower() == i.name.lower():
                 _integration = i
                 break
         else:
             raise AppException("Integration not found.")
+
         response = self.controller.integrations.attach_items(
-            project, folder, _integration, folder_path
+            project=project,
+            folder=folder,
+            integration=_integration,
+            folder_path=folder_path,
+            query=query,
+            item_name_column=item_name_column,
+            custom_item_name=custom_item_name,
+            component_mapping=component_mapping,
         )
         if response.errors:
             raise AppException(response.errors)
@@ -3593,7 +3661,7 @@ def copy_items(
             "skip", "replace", "replace_annotations_only"
         ] = "skip",
     ):
-        """Copy images in bulk between folders in a project
+        """Copy items in bulk between folders in a project
 
         :param source: project name (root) or folder path to pick items from (e.g., “project1/folder1”).
         :type source: str
@@ -3657,7 +3725,7 @@ def move_items(
             "skip", "replace", "replace_annotations_only"
         ] = "skip",
     ):
-        """Move images in bulk between folders in a project
+        """Move items in bulk between folders in a project
 
         :param source: project name (root) or folder path to pick items from (e.g., “project1/folder1”).
         :type source: str

src/superannotate/lib/core/serviceproviders.py

@@ -490,6 +490,7 @@ def get_upload_chunks(
         self,
         project: entities.ProjectEntity,
         item_ids: List[int],
+        chunk_size: int = 1000,
     ) -> Dict[str, List]:
         raise NotImplementedError
 
@@ -592,6 +593,7 @@ def attach_items(
         folder: entities.FolderEntity,
         integration: entities.IntegrationEntity,
         folder_name: str = None,
+        options: Dict[str, str] = None,
     ) -> ServiceResponse:
         raise NotImplementedError
 

src/superannotate/lib/core/usecases/integrations.py

@@ -1,8 +1,13 @@
-from typing import List
+from typing import Dict
+from typing import Optional
 
+from lib.core.conditions import Condition
+from lib.core.conditions import CONDITION_EQ as EQ
 from lib.core.entities import FolderEntity
 from lib.core.entities import IntegrationEntity
 from lib.core.entities import ProjectEntity
+from lib.core.entities.integrations import IntegrationTypeEnum
+from lib.core.enums import ProjectType
 from lib.core.exceptions import AppException
 from lib.core.reporter import Reporter
 from lib.core.response import Response
@@ -25,6 +30,11 @@ def execute(self) -> Response:
 
 
 class AttachIntegrations(BaseReportableUseCase):
+    MULTIMODAL_INTEGRATIONS = [
+        IntegrationTypeEnum.DATABRICKS,
+        IntegrationTypeEnum.SNOWFLAKE,
+    ]
+
     def __init__(
         self,
         reporter: Reporter,
@@ -33,46 +43,137 @@ def __init__(
         service_provider: BaseServiceProvider,
         integration: IntegrationEntity,
         folder_path: str = None,
+        query: Optional[str] = None,
+        item_name_column: Optional[str] = None,
+        custom_item_name: Optional[str] = None,
+        component_mapping: Optional[Dict[str, str]] = None,
     ):
-
         super().__init__(reporter)
         self._project = project
         self._folder = folder
         self._integration = integration
         self._service_provider = service_provider
         self._folder_path = folder_path
+        self._query = query
+        self._item_name_column = item_name_column
+        self._custom_item_name = custom_item_name
+        self._component_mapping = component_mapping
+        self._options = {}  # using only for Databricks and Snowflake
+        self._item_category_column = None
 
     @property
     def _upload_path(self):
         return f"{self._project.name}{f'/{self._folder.name}' if self._folder.name != 'root' else ''}"
 
-    def execute(self) -> Response:
-        integrations: List[
-            IntegrationEntity
-        ] = self._service_provider.integrations.list().data.integrations
-        integration_name_lower = self._integration.name.lower()
-        integration = next(
-            (i for i in integrations if i.name.lower() == integration_name_lower), None
+    def validate_integration(self):
+        # TODO add support in next iterations
+        if self._integration.type == IntegrationTypeEnum.SNOWFLAKE:
+            raise AppException(
+                "Attaching items is not supported with Snowflake integration."
+            )
+
+        if self._integration.type in self.MULTIMODAL_INTEGRATIONS:
+            if self._project.type != ProjectType.MULTIMODAL:
+                raise AppException(
+                    f"{self._integration.name} integration is supported only for Multimodal projects."
+                )
+
+    def validate_options_for_multimodal_integration(self):
+        if self._integration.type in self.MULTIMODAL_INTEGRATIONS:
+            if self._item_name_column and self._custom_item_name:
+                raise AppException(
+                    "‘item_name_column and custom_item_name cannot be used simultaneously."
+                )
+
+            if not self._item_name_column and not self._custom_item_name:
+                raise AppException(
+                    "Either item_name_column or custom_item_name is required."
+                )
+
+            if not all((self._query, self._component_mapping)):
+                raise AppException(
+                    f"{self._integration.name} integration requires both a query and component_mapping."
+                )
+
+            category_setting: bool = bool(
+                next(
+                    (
+                        setting.value
+                        for setting in self._service_provider.projects.list_settings(
+                            self._project
+                        ).data
+                        if setting.attribute == "CategorizeItems"
+                    ),
+                    None,
+                )
+            )
+            if (
+                not category_setting
+                and "_item_category" in self._component_mapping.values()
+            ):
+                raise AppException(
+                    "Item Category must be enabled for a project to use _item_category"
+                )
+
+            self._item_category_column = next(
+                (
+                    k
+                    for k, v in self._component_mapping.items()
+                    if v == "_item_category"
+                ),
+                None,
+            )
+            if self._item_category_column:
+                del self._component_mapping[self._item_category_column]
+
+            sa_components = [
+                c.name.lower()
+                for c in self._service_provider.annotation_classes.list(
+                    condition=Condition("project_id", self._project.id, EQ)
+                ).data
+            ]
+
+            for i in self._component_mapping.values():
+                if i.lower() not in sa_components:
+                    raise AppException(
+                        f"Component mapping contains invalid component ID: `{i}`"
+                    )
+
+    def generate_options_for_multimodal_integration(self):
+        self._options["query"] = self._query
+        self._options["item_name"] = (
+            self._custom_item_name if self._custom_item_name else self._item_name_column
         )
-        if integration:
+        self._options["prefix"] = True if self._custom_item_name else False
+        self._options["column_class_map"] = self._component_mapping
+        if self._item_category_column:
+            self._options["item_category"] = self._item_category_column
+
+    def execute(self) -> Response:
+        if self.is_valid():
+            if self._integration.type in self.MULTIMODAL_INTEGRATIONS:
+                self.generate_options_for_multimodal_integration()
+
             self.reporter.log_info(
                 "Attaching file(s) from "
-                f"{integration.root}{f'/{self._folder_path}' if self._folder_path else ''} "
+                f"{self._integration.root}{f'/{self._folder_path}' if self._folder_path else ''} "
                 f"to {self._upload_path}. This may take some time."
             )
-            attached = self._service_provider.integrations.attach_items(
+
+            attache_response = self._service_provider.integrations.attach_items(
                 project=self._project,
                 folder=self._folder,
-                integration=integration,
-                folder_name=self._folder_path,
+                integration=self._integration,
+                folder_name=self._folder_path
+                if self._integration.type not in self.MULTIMODAL_INTEGRATIONS
+                else None,
+                options=self._options if self._options else None,
             )
-            if not attached:
+            if not attache_response.ok:
                 self._response.errors = AppException(
                     f"An error occurred for {self._integration.name}. Please make sure: "
                     "\n - The bucket exists."
                     "\n - The connection is valid."
                     "\n - The path to a specified directory is correct."
                 )
-        else:
-            self._response.errors = AppException("Integration not found.")
-        return self._response
+            return self._response