Merge pull request #736 from superannotateai/FRIDAY_2985

Update get/upload annotations interface

Author: VaghinakDev

pytest.ini

@@ -3,4 +3,4 @@ minversion = 3.7
 log_cli=true
 python_files = test_*.py
 ;pytest_plugins = ['pytest_profiling']
-;addopts = -n 4 --dist loadscope
+addopts = -n 4 --dist loadscope

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

@@ -1941,41 +1941,54 @@ def download_image(
         logger.info(f"Downloaded image {image_name} to {local_dir_path} ")
         return response.data
 
+
     def upload_annotations(
-        self, project: NotEmptyStr, annotations: List[dict], keep_status: bool = None
+            self,
+            project: NotEmptyStr,
+            annotations: List[dict],
+            keep_status: bool = None,
+            *,
+            data_spec: Literal['default', 'multimodal'] = 'default'
     ):
-        """Uploads a list of annotation dicts as annotations to the SuperAnnotate directory.
+        """Uploads a list of annotation dictionaries to the specified SuperAnnotate project or folder.
 
-        :param project: project name or folder path (e.g., "project1/folder1")
-        :type project: str or dict
+        :param project: The project name or folder path where annotations will be uploaded
+            (e.g., "project1/folder1").
+        :type project: str
 
-        :param annotations:  list of annotation dictionaries corresponding to SuperAnnotate format
-        :type annotations: list of dicts
+        :param annotations: A list of annotation dictionaries formatted according to the SuperAnnotate standards.
+        :type annotations: list of dict
 
-        :param keep_status: If False, the annotation status will be automatically
-            updated to "InProgress," otherwise the current status will be kept.
-        :type keep_status: bool
+        :param keep_status: If False, the annotation status will be automatically updated to "InProgress."
+            If True, the current status will remain unchanged.
+        :type keep_status: bool, optional
+
+        :param data_spec: Specifies the format for processing and transforming annotations before upload.
 
+            Options are:
+                    - default: Retains the annotations in their original format.
+                    - multimodal: Converts annotations for multimodal projects, optimizing for
+                                     compact and modality-specific data representation.
+        :type data_spec: str, optional
 
-        :return: a dictionary containing lists of successfully uploaded, failed and skipped name
+        :return: A dictionary containing the results of the upload, categorized into successfully uploaded,
+            failed, and skipped annotations.
         :rtype: dict
 
-        Response Example:
-        ::
+        Response Example::
 
             {
                "succeeded": [],
-               "failed":[],
+               "failed": [],
                "skipped": []
             }
 
-        Example Usage with JSONL Upload:
-        ::
+        Example Usage with JSONL Upload for Multimodal Projects::
+
             import json
             from pathlib import Path
             from superannotate import SAClient
 
-            # Assuming annotations are stored in JSONL format
             annotations_path = Path("annotations.jsonl")
             annotations = []
 
@@ -1984,16 +1997,16 @@ def upload_annotations(
                 for line in f:
                     annotations.append(json.loads(line))
 
-            # Initialize the Superannotate client
+            # Initialize the SuperAnnotate client
             sa = SAClient()
 
             # Call the upload_annotations function
-            response = client.upload_annotations(
+            response = sa.upload_annotations(
                 project="project1/folder1",
                 annotations=annotations,
-                keep_status=True
+                keep_status=True,
+                data_spec='multimodal'
             )
-
         """
         if keep_status is not None:
             warnings.warn(
@@ -2009,6 +2022,7 @@ def upload_annotations(
             annotations=annotations,
             keep_status=keep_status,
             user=self.controller.current_user,
+            output_format=data_spec
         )
         if response.errors:
             raise AppException(response.errors)
@@ -2483,6 +2497,8 @@ def get_annotations(
         self,
         project: Union[NotEmptyStr, int],
         items: Optional[Union[List[NotEmptyStr], List[int]]] = None,
+        *,
+        data_spec: Literal['default', 'multimodal'] = 'default'
     ):
         """Returns annotations for the given list of items.
 
@@ -2492,6 +2508,29 @@ def get_annotations(
         :param items:  item names. If None, all the items in the specified directory will be used.
         :type items: list of strs or list of ints
 
+        :param data_spec: Specifies the format for processing and transforming annotations before upload.
+
+            Options are:
+                    - default: Retains the annotations in their original format.
+                    - multimodal: Converts annotations for multimodal projects, optimizing for
+                                     compact and modality-specific data representation.
+
+        :type data_spec: str, optional
+
+        Example Usage of Multimodal Projects::
+
+            from superannotate import SAClient
+
+
+            sa = SAClient()
+
+            # Call the upload_annotations function
+            response = sa.upload_annotations(
+                project="project1/folder1",
+                items=["item_1", "item_2"],
+                data_spec='multimodal'
+            )
+
         :return: list of annotations
         :rtype: list of dict
         """
@@ -2502,7 +2541,10 @@ def get_annotations(
             folder = self.controller.get_folder_by_id(
                 project_id=project.id, folder_id=project.folder_id
             ).data
-        response = self.controller.annotations.list(project, folder, items)
+        response = self.controller.annotations.list(
+            project, folder, items,
+            transform_version='llmJsonV2' if data_spec == 'multimodal' else None
+        )
         if response.errors:
             raise AppException(response.errors)
         return response.data
@@ -2825,7 +2867,7 @@ def list_items(
         project: Union[NotEmptyStr, int],
         folder: Optional[Union[NotEmptyStr, int]] = None,
         *,
-        include: List[Literal["custom_metadata"]] = None,
+        include: List[Literal["custom_metadata", "category"]] = None,
         **filters,
     ):
         """

src/superannotate/lib/infrastructure/controller.py

@@ -780,9 +780,9 @@ def upload_multiple(
         annotations: List[dict],
         keep_status: bool,
         user: UserEntity,
-        transform_version: str = None,
+        output_format: str = None,
     ):
-        if project.type == ProjectType.MULTIMODAL:
+        if project.type == ProjectType.MULTIMODAL and output_format == 'multimodal':
             use_case = usecases.UploadMultiModalAnnotationsUseCase(
                 reporter=Reporter(),
                 project=project,
@@ -791,7 +791,7 @@ def upload_multiple(
                 service_provider=self.service_provider,
                 keep_status=keep_status,
                 user=user,
-                transform_version=transform_version,
+                transform_version='llmJsonV2',
             )
         else:
             use_case = usecases.UploadAnnotationsUseCase(
@@ -802,7 +802,7 @@ def upload_multiple(
                 service_provider=self.service_provider,
                 keep_status=keep_status,
                 user=user,
-                transform_version=transform_version,
+                transform_version=None,
             )
         return use_case.execute()
 

tests/integration/annotations/test_upload_annotations.py

@@ -179,21 +179,21 @@ def test_upload_to_root(self):
             data[0]["metadata"]["folder_name"] = ""
             data[0]["metadata"]["folder_name"] = "root"
             del data[0]["metadata"]["folder_name"]
-            response = sa.upload_annotations(self.PROJECT_NAME, annotations=data)
+            response = sa.upload_annotations(self.PROJECT_NAME, annotations=data, data_spec='multimodal')
             assert len(response["succeeded"]) == 3
-            annotations = sa.get_annotations(f"{self.PROJECT_NAME}")
-            assert all([len(i["instances"]) == 3 for i in annotations]) is True
+            annotations = sa.get_annotations(f"{self.PROJECT_NAME}", data_spec='multimodal')
+            assert all([len(i["data"].keys()) == 3 for i in annotations]) is True
 
     def test_upload_from_root_to_folder(self):
         with open(self.JSONL_ANNOTATIONS_PATH) as f:
             data = [json.loads(line) for line in f]
-            response = sa.upload_annotations(self.PROJECT_NAME, annotations=data)
+            response = sa.upload_annotations(self.PROJECT_NAME, annotations=data, data_spec='multimodal')
             assert len(response["succeeded"]) == 3
-            annotations = sa.get_annotations(f"{self.PROJECT_NAME}/test_folder")
-            assert all([len(i["instances"]) == 3 for i in annotations]) is True
+            annotations = sa.get_annotations(f"{self.PROJECT_NAME}/test_folder", data_spec='multimodal')
+            assert all([len(i["data"].keys()) == 3 for i in annotations]) is True
             folders = sa.search_folders(self.PROJECT_NAME)
             assert len(folders) == 1
-            sa.upload_annotations(self.PROJECT_NAME, annotations=data)
+            sa.upload_annotations(self.PROJECT_NAME, annotations=data, data_spec='multimodal')
             assert len(folders) == 1
 
     def test_error_upload_from_folder_to_folder_(self):
@@ -204,11 +204,11 @@ def test_error_upload_from_folder_to_folder_(self):
                 AppException,
                 "You can't include a folder when uploading from within a folder.",
             ):
-                sa.upload_annotations(f"{self.PROJECT_NAME}/tmp", annotations=data)
+                sa.upload_annotations(f"{self.PROJECT_NAME}/tmp", annotations=data, data_spec='multimodal')
 
     def test_upload_with_categories(self):
         with open(self.JSONL_ANNOTATIONS_WITH_CATEGORIES_PATH) as f:
             data = [json.loads(line) for line in f]
-            sa.upload_annotations(f"{self.PROJECT_NAME}", annotations=data)
-            annotations = sa.get_annotations(f"{self.PROJECT_NAME}/test_folder")
+            sa.upload_annotations(f"{self.PROJECT_NAME}", annotations=data, data_spec='multimodal')
+            annotations = sa.get_annotations(f"{self.PROJECT_NAME}/test_folder", data_spec='multimodal')
             assert len(annotations) == 3