Merge branch 'develop' into FRIDAY_3645

Author: VaghinakDev

CHANGELOG.rst

@@ -6,6 +6,12 @@ History
 
 All release highlights of this project will be documented in this file.
 
+4.4.32 - March 4, 2025
+_____________________
+
+**Fixed**
+
+    - ``SAClient.item_context`` Fixed an issue where setting a component value would overwrite existing comments and other associated data. 
 
 4.4.31 - Feb 27, 2025
 _____________________

src/superannotate/__init__.py

@@ -3,7 +3,8 @@
 import sys
 
 
-__version__ = "4.4.33dev1"
+__version__ = "4.4.32dev3"
+
 
 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

@@ -1699,7 +1699,8 @@ def prepare_export(
 
              - integration_name: The name of the integration within the platform that is being used.
              - format: The format in which the data will be exported in multimodal projects.
-               It can be either CSV or JSON. If None, the data will be exported in the default JSON format.
+               The data can be exported in CSV, JSON, or JSONL format. If None, the data will be exported
+               in the default JSON format.
         :return: metadata object of the prepared export
         :rtype: dict
 
@@ -1737,6 +1738,8 @@ def prepare_export(
             export_type = export_type.lower()
             if export_type == "csv":
                 _export_type = 3
+            elif export_type == "jsonl":
+                _export_type = 4
         response = self.controller.prepare_export(
             project_name=project_name,
             folder_names=folders,
@@ -3440,7 +3443,7 @@ def list_items(
         exclude = {"meta", "annotator_email", "qa_email"}
         if not include_custom_metadata:
             exclude.add("custom_metadata")
-        return BaseSerializer.serialize_iterable(res, exclude=exclude)
+        return BaseSerializer.serialize_iterable(res, exclude=exclude, by_alias=False)
 
     def list_projects(
         self,
@@ -3828,6 +3831,7 @@ def download_annotations(
         items: Optional[List[NotEmptyStr]] = None,
         recursive: bool = False,
         callback: Callable = None,
+        data_spec: Literal["default", "multimodal"] = "default",
     ):
         """Downloads annotation JSON files of the selected items to the local directory.
 
@@ -3853,6 +3857,31 @@ def download_annotations(
          The function receives each annotation as an argument and the returned value will be applied to the download.
         :type callback: callable
 
+        :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 multimodal-specific data representation.
+
+        :type data_spec: str, optional
+
+        Example Usage of Multimodal Projects::
+
+            from superannotate import SAClient
+
+
+            sa = SAClient()
+
+            # Call the get_annotations function
+            response = sa.download_annotations(
+                project="project1/folder1",
+                path="path/to/download",
+                items=["item_1", "item_2"],
+                data_spec='multimodal'
+            )
+
+
         :return: local path of the downloaded annotations folder.
         :rtype: str
         """
@@ -3865,6 +3894,7 @@ def download_annotations(
             recursive=recursive,
             item_names=items,
             callback=callback,
+            transform_version="llmJsonV2" if data_spec == "multimodal" else None,
         )
         if response.errors:
             raise AppException(response.errors)

src/superannotate/lib/core/entities/__init__.py

@@ -4,6 +4,7 @@
 from lib.core.entities.classes import AnnotationClassEntity
 from lib.core.entities.folder import FolderEntity
 from lib.core.entities.integrations import IntegrationEntity
+from lib.core.entities.items import CategoryEntity
 from lib.core.entities.items import ClassificationEntity
 from lib.core.entities.items import DocumentEntity
 from lib.core.entities.items import ImageEntity
@@ -12,7 +13,6 @@
 from lib.core.entities.items import TiledEntity
 from lib.core.entities.items import VideoEntity
 from lib.core.entities.project import AttachmentEntity
-from lib.core.entities.project import CategoryEntity
 from lib.core.entities.project import ContributorEntity
 from lib.core.entities.project import CustomFieldEntity
 from lib.core.entities.project import ProjectEntity

src/superannotate/lib/core/entities/filters.py

@@ -29,6 +29,8 @@ class ItemFilters(BaseFilters):
     assignments__user_role__in: Optional[List[str]]
     assignments__user_role__ne: Optional[str]
     assignments__user_role__notin: Optional[List[str]]
+    categories__value: Optional[str]
+    categories__value__in: Optional[List[str]]
 
 
 class ProjectFilters(BaseFilters):

src/superannotate/lib/core/entities/items.py

@@ -2,7 +2,7 @@
 from typing import Optional
 
 from lib.core.entities.base import BaseItemEntity
-from lib.core.entities.base import TimedBaseModel
+from lib.core.entities.project import TimedBaseModel
 from lib.core.enums import ApprovalStatus
 from lib.core.enums import ProjectType
 from lib.core.pydantic_v1 import Extra
@@ -18,9 +18,17 @@ class Config:
         extra = Extra.ignore
 
 
+class CategoryEntity(TimedBaseModel):
+    id: int
+    value: str = Field(None, alias="name")
+
+    class Config:
+        extra = Extra.ignore
+
+
 class MultiModalItemCategoryEntity(TimedBaseModel):
     id: int = Field(None, alias="category_id")
-    name: str = Field(None, alias="category_name")
+    value: str = Field(None, alias="category_name")
 
     class Config:
         extra = Extra.ignore

src/superannotate/lib/core/entities/project.py

@@ -187,8 +187,3 @@ def is_system(self):
 
     class Config:
         extra = Extra.ignore
-
-
-class CategoryEntity(BaseModel):
-    id: Optional[int]
-    name: Optional[str]

src/superannotate/lib/core/serviceproviders.py

@@ -506,6 +506,7 @@ async def download_big_annotation(
         download_path: str,
         item: entities.BaseItemEntity,
         callback: Callable = None,
+        transform_version: str = None,
     ):
         raise NotImplementedError
 
@@ -518,6 +519,7 @@ async def download_small_annotations(
         download_path: str,
         item_ids: List[int],
         callback: Callable = None,
+        transform_version: str = None,
     ):
         raise NotImplementedError
 
@@ -701,6 +703,12 @@ class BaseServiceProvider:
     def get_role_id(self, project: entities.ProjectEntity, role_name: str) -> int:
         raise NotImplementedError
 
+    @abstractmethod
+    def get_category_id(
+        self, project: entities.ProjectEntity, category_name: str
+    ) -> int:
+        raise NotImplementedError
+
     @abstractmethod
     def get_role_name(self, project: entities.ProjectEntity, role_id: int) -> str:
         raise NotImplementedError

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

@@ -1634,6 +1634,7 @@ def __init__(
         item_names: List[str],
         service_provider: BaseServiceProvider,
         callback: Callable = None,
+        transform_version=None,
     ):
         super().__init__(reporter)
         self._config = config
@@ -1645,6 +1646,7 @@ def __init__(
         self._service_provider = service_provider
         self._callback = callback
         self._big_file_queue = None
+        self._transform_version = transform_version
 
     def validate_items(self):
         if self._item_names:
@@ -1724,6 +1726,7 @@ async def download_small_annotations(
             reporter=self.reporter,
             download_path=f"{export_path}{'/' + self._folder.name if not self._folder.is_root else ''}",
             callback=self._callback,
+            transform_version=self._transform_version,
         )
 
     async def run_workers(
@@ -2098,8 +2101,10 @@ def execute(self):
                 if categorization_enabled:
                     item_id_category_map = {}
                     for item_name in uploaded_annotations:
-                        category = name_annotation_map[item_name]["metadata"].get(
-                            "item_category"
+                        category = (
+                            name_annotation_map[item_name]["metadata"]
+                            .get("item_category", {})
+                            .get("value")
                         )
                         if category:
                             item_id_category_map[name_item_map[item_name].id] = category

src/superannotate/lib/infrastructure/controller.py

@@ -972,6 +972,7 @@ def download(
         recursive: bool,
         item_names: Optional[List[str]],
         callback: Optional[Callable],
+        transform_version: str,
     ):
         use_case = usecases.DownloadAnnotations(
             config=self._config,
@@ -983,6 +984,7 @@ def download(
             item_names=item_names,
             service_provider=self.service_provider,
             callback=callback,
+            transform_version=transform_version,
         )
         return use_case.execute()