superannotate 4.4.27__tar.gz → 4.4.29.dev1__tar.gz

{superannotate-4.4.27/src/superannotate.egg-info → superannotate-4.4.29.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: superannotate
-Version: 4.4.27
+Version: 4.4.29.dev1
 Summary: Python SDK to SuperAnnotate platform
 Home-page: https://github.com/superannotateai/superannotate-python-sdk
 Author: SuperAnnotate AI

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/__init__.py

@@ -3,7 +3,7 @@ import os
 import sys
 
 
-__version__ = "4.4.27"
+__version__ = "4.4.29dev1"
 
 os.environ.update({"sa_version": __version__})
 sys.path.append(os.path.split(os.path.realpath(__file__))[0])
@@ -15,6 +15,7 @@ from lib.core import PACKAGE_VERSION_UPGRADE
 from lib.core import PACKAGE_VERSION_INFO_MESSAGE
 from lib.core import PACKAGE_VERSION_MAJOR_UPGRADE
 from lib.core.exceptions import AppException
+from lib.core.exceptions import FileChangedError
 from superannotate.lib.app.input_converters import convert_project_type
 from superannotate.lib.app.input_converters import export_annotation
 from superannotate.lib.app.input_converters import import_annotation
@@ -30,6 +31,7 @@ __all__ = [
     # Utils
     "enums",
     "AppException",
+    "FileChangedError",
     "import_annotation",
     "export_annotation",
     "convert_project_type",

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/lib/app/interface/sdk_interface.py

@@ -5,6 +5,7 @@ import json
 import logging
 import os
 import sys
+import typing
 import warnings
 from pathlib import Path
 from typing import Any
@@ -28,11 +29,13 @@ import boto3
 from tqdm import tqdm
 
 import lib.core as constants
+from lib.infrastructure.controller import Controller
 from lib.app.helpers import get_annotation_paths
 from lib.app.helpers import get_name_url_duplicated_from_csv
 from lib.app.helpers import wrap_error as wrap_validation_errors
 from lib.app.interface.base_interface import BaseInterfaceFacade
 from lib.app.interface.base_interface import TrackableMeta
+
 from lib.app.interface.types import EmailStr
 from lib.app.serializers import BaseSerializer
 from lib.app.serializers import FolderSerializer
@@ -45,7 +48,7 @@ from lib.core.conditions import CONDITION_EQ as EQ
 from lib.core.conditions import Condition
 from lib.core.jsx_conditions import Filter, OperatorEnum
 from lib.core.conditions import EmptyCondition
-from lib.core.entities import AttachmentEntity
+from lib.core.entities import AttachmentEntity, FolderEntity, BaseItemEntity
 from lib.core.entities import SettingEntity
 from lib.core.entities.classes import AnnotationClassEntity
 from lib.core.entities.classes import AttributeGroup
@@ -61,6 +64,9 @@ from lib.core.pydantic_v1 import ValidationError
 from lib.core.pydantic_v1 import constr
 from lib.core.pydantic_v1 import conlist
 from lib.core.pydantic_v1 import parse_obj_as
+from lib.infrastructure.annotation_adapter import BaseMultimodalAnnotationAdapter
+from lib.infrastructure.annotation_adapter import MultimodalSmallAnnotationAdapter
+from lib.infrastructure.annotation_adapter import MultimodalLargeAnnotationAdapter
 from lib.infrastructure.utils import extract_project_folder
 from lib.infrastructure.validators import wrap_error
 
@@ -69,7 +75,6 @@ logger = logging.getLogger("sa")
 # NotEmptyStr = TypeVar("NotEmptyStr", bound=constr(strict=True, min_length=1))
 NotEmptyStr = constr(strict=True, min_length=1)
 
-
 PROJECT_STATUS = Literal["NotStarted", "InProgress", "Completed", "OnHold"]
 
 PROJECT_TYPE = Literal[
@@ -82,7 +87,6 @@ PROJECT_TYPE = Literal[
     "Multimodal",
 ]
 
-
 APPROVAL_STATUS = Literal["Approved", "Disapproved", None]
 
 IMAGE_QUALITY = Literal["compressed", "original"]
@@ -110,6 +114,87 @@ class Attachment(TypedDict, total=False):
     integration: NotRequired[str]  # noqa
 
 
+class ItemContext:
+    def __init__(
+        self,
+        controller: Controller,
+        project: Project,
+        folder: FolderEntity,
+        item: BaseItemEntity,
+        overwrite: bool = True,
+    ):
+        self.controller = controller
+        self.project = project
+        self.folder = folder
+        self.item = item
+        self._annotation_adapter: Optional[BaseMultimodalAnnotationAdapter] = None
+        self._overwrite = overwrite
+        self._annotation = None
+
+    def _set_small_annotation_adapter(self, annotation: dict = None):
+        self._annotation_adapter = MultimodalSmallAnnotationAdapter(
+            project=self.project,
+            folder=self.folder,
+            item=self.item,
+            controller=self.controller,
+            overwrite=self._overwrite,
+            annotation=annotation,
+        )
+
+    def _set_large_annotation_adapter(self, annotation: dict = None):
+        self._annotation_adapter = MultimodalLargeAnnotationAdapter(
+            project=self.project,
+            folder=self.folder,
+            item=self.item,
+            controller=self.controller,
+            annotation=annotation,
+        )
+
+    @property
+    def annotation_adapter(self) -> BaseMultimodalAnnotationAdapter:
+        if self._annotation_adapter is None:
+            res = self.controller.service_provider.annotations.get_upload_chunks(
+                project=self.project, item_ids=[self.item.id]
+            )
+            small_item = next(iter(res["small"]), None)
+            if small_item:
+                self._set_small_annotation_adapter()
+            else:
+                self._set_large_annotation_adapter()
+        return self._annotation_adapter
+
+    @property
+    def annotation(self):
+        return self.annotation_adapter.annotation
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type:
+            return False
+
+        self.save()
+        return True
+
+    def save(self):
+        if len(json.dumps(self.annotation).encode("utf-8")) > 16 * 1024 * 1024:
+            self._set_large_annotation_adapter(self.annotation)
+        else:
+            self._set_small_annotation_adapter(self.annotation)
+        self._annotation_adapter.save()
+
+    def get_metadata(self):
+        return self.annotation["metadata"]
+
+    def get_component_value(self, component_id: str):
+        return self.annotation_adapter.get_component_value(component_id)
+
+    def set_component_value(self, component_id: str, value: Any):
+        self.annotation_adapter.set_component_value(component_id, value)
+        return self
+
+
 class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
     """Create SAClient instance to authorize SDK in a team scope.
     In case of no argument has been provided, SA_TOKEN environmental variable
@@ -193,6 +278,55 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
         response = self.controller.get_team()
         return TeamSerializer(response.data).serialize()
 
+    def get_component_config(self, project: Union[NotEmptyStr, int], component_id: str):
+        """
+        Retrieves the configuration for a given project and component ID.
+
+        :param project: The identifier of the project, which can be a string or an integer representing the project ID.
+        :type project: Union[str, int]
+
+        :param component_id: The ID of the component for which the context is to be retrieved.
+        :type component_id: str
+
+        :return: The context associated with the `webComponent`.
+        :rtype: Any
+
+        :raises AppException: If the project type is not `MULTIMODAL` or no `webComponent` context is found.
+        """
+
+        def retrieve_context(
+            component_data: List[dict], component_pk: str
+        ) -> Tuple[bool, typing.Any]:
+            for component in component_data:
+                if (
+                    component["type"] == "webComponent"
+                    and component["id"] == component_pk
+                ):
+                    return True, component.get("context")
+                if component["type"] == "group" and "children" in component:
+                    found, val = retrieve_context(component["children"], component_pk)
+                    if found:
+                        return found, val
+            return False, None
+
+        project = (
+            self.controller.get_project_by_id(project).data
+            if isinstance(project, int)
+            else self.controller.get_project(project)
+        )
+        if project.type != ProjectType.MULTIMODAL:
+            raise AppException(
+                "This function is only supported for Multimodal projects."
+            )
+
+        editor_template = self.controller.projects.get_editor_template(project)
+        components = editor_template.get("components", [])
+
+        _found, _context = retrieve_context(components, component_id)
+        if not _found:
+            raise AppException("No component context found for project.")
+        return _context
+
     def search_team_contributors(
         self,
         email: EmailStr = None,
@@ -2616,7 +2750,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
             ]
         """
         project, folder = self.controller.get_project_folder_by_path(project)
-        query_kwargs = {}
+        query_kwargs = {"include": ["assignments"]}
         if name_contains:
             query_kwargs["name__contains"] = name_contains
         if annotation_status:
@@ -2634,7 +2768,9 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
                     f"{project.name}{f'/{folder.name}' if not folder.is_root else ''}"
                 )
                 _items = self.controller.items.list_items(
-                    project, folder, **query_kwargs
+                    project,
+                    folder,
+                    **query_kwargs,
                 )
                 for i in _items:
                     i.path = path
@@ -2780,7 +2916,10 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
                 ).data
             else:
                 folder = self.controller.get_folder(project, folder)
-        include = include or []
+        _include = {"assignments"}
+        if include:
+            _include.update(set(include))
+        include = list(_include)
         include_custom_metadata = "custom_metadata" in include
         if include_custom_metadata:
             include.remove("custom_metadata")
@@ -2792,7 +2931,7 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
                 project=project, item_ids=[i.id for i in res]
             )
             for i in res:
-                i["custom_metadata"] = item_custom_fields[i.id]
+                i.custom_metadata = item_custom_fields[i.id]
         exclude = {"meta", "annotator_email", "qa_email"}
         if include:
             if "custom_metadata" not in include:
@@ -3540,3 +3679,115 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
         )
         if response.errors:
             raise AppException(response.errors)
+
+    def item_context(
+        self,
+        path: Union[str, Tuple[NotEmptyStr, NotEmptyStr], Tuple[int, int]],
+        item: Union[NotEmptyStr, int],
+        overwrite: bool = True,
+    ) -> ItemContext:
+        """
+        Creates an “ItemContext” for managing item annotations and metadata.
+
+        This function allows you to manage annotations and metadata for an item located within a
+        specified project and folder. The path to the item can be provided either as a string or a tuple,
+        and you can specify the item using its name or ID.
+        It returns an “ItemContext” that automatically saves any changes to annotations when the context is exited.
+
+        :param path: Specifies the project and folder containing the item. Can be one of:
+            - A string path, e.g., "project_name/folder_name".
+            - A tuple of strings, e.g., ("project_name", "folder_name").
+            - A tuple of integers (IDs), e.g., (project_id, folder_id).
+        :type path: Union[str, Tuple[str, str], Tuple[int, int]]
+
+        :param item: The name or ID of the item for which the context is being created.
+        :type item: Union[str, int]
+
+        :param overwrite: If `True`, annotations are overwritten during saving. Defaults is `True`.
+            If `False`, raises a `FileChangedError` if the item was modified concurrently.
+        :type overwrite: bool
+
+        :raises AppException: If the provided `path` is invalid or if the item cannot be located.
+
+        :return: An `ItemContext` object to manage the specified item's annotations and metadata.
+        :rtype: ItemContext
+
+        **Examples:**
+
+        Create an `ItemContext` using a string path and item name:
+
+        .. code-block:: python
+
+            with client.item_context("project_name/folder_name", "item_name") as item_context:
+                metadata = item_context.get_metadata()
+                value = item_context.get_component_value("prompts")
+                item_context.set_component_value("prompts", value)
+
+        Create an `ItemContext` using a tuple of strings and an item ID:
+
+        .. code-block:: python
+
+            with client.item_context(("project_name", "folder_name"), 12345) as context:
+                metadata = context.get_metadata()
+                print(metadata)
+
+        Create an `ItemContext` using a tuple of IDs and an item name:
+
+        .. code-block:: python
+
+            with client.item_context((101, 202), "item_name") as context:
+                value = context.get_component_value("component_id")
+                print(value)
+
+        Save annotations automatically after modifying component values:
+
+        .. code-block:: python
+
+            with client.item_context("project_name/folder_name", "item_name", overwrite=True) as context:
+                context.set_component_value("component_id", "new_value")
+            # No need to call .save(), changes are saved automatically on context exit.
+
+        Handle exceptions during context execution:
+
+        .. code-block:: python
+
+            from superannotate import FileChangedError
+
+            try:
+                with client.item_context((101, 202), "item_name") as context:
+                    context.set_component_value("component_id", "new_value")
+            except FileChangedError as e:
+                print(f"An error occurred: {e}")
+        """
+        if isinstance(path, str):
+            project, folder = self.controller.get_project_folder_by_path(path)
+        elif len(path) == 2 and all([isinstance(i, str) for i in path]):
+            project = self.controller.get_project(path[0])
+            folder = self.controller.get_folder(project, path[1])
+        elif len(path) == 2 and all([isinstance(i, int) for i in path]):
+            project = self.controller.get_project_by_id(path[0]).data
+            folder = self.controller.get_folder_by_id(path[1], project.id).data
+        else:
+            raise AppException("Invalid path provided.")
+        if project.type != ProjectType.MULTIMODAL:
+            raise AppException(
+                "This function is only supported for Multimodal projects."
+            )
+        if isinstance(item, int):
+            _item = self.controller.get_item_by_id(item_id=item, project=project)
+        else:
+            items = self.controller.items.list_items(project, folder, name=item)
+            if not items:
+                raise AppException("Item not found.")
+            _item = items[0]
+        if project.type != ProjectType.MULTIMODAL:
+            raise AppException(
+                f"The function is not supported for {project.type.name} projects."
+            )
+        return ItemContext(
+            controller=self.controller,
+            project=project,
+            folder=folder,
+            item=_item,
+            overwrite=overwrite,
+        )

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/lib/core/__init__.py

@@ -178,6 +178,7 @@ PROJECT_SETTINGS_VALID_ATTRIBUTES = [
     "UploadFileType",
     "Tokenization",
     "ImageAutoAssignEnable",
+    "TemplateState",
 ]
 
 __alL__ = (

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/lib/core/enums.py

@@ -174,6 +174,8 @@ class IntegrationTypeEnum(BaseTitledEnum):
     GCP = "gcp", 2
     AZURE = "azure", 3
     CUSTOM = "custom", 4
+    DATABRICKS = "databricks", 5
+    SNOWFLAKE = "snowflake", 6
 
 
 class TrainingStatus(BaseTitledEnum):

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/lib/core/exceptions.py

@@ -35,3 +35,9 @@ class PathError(AppException):
     """
     User input Error
     """
+
+
+class FileChangedError(AppException):
+    """
+    User input Error
+    """

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/lib/core/service_types.py

@@ -114,6 +114,10 @@ class ServiceResponse(BaseModel):
             return 199 < self.status < 300
         return False
 
+    def raise_for_status(self):
+        if not self.ok:
+            raise AppException(self.error)
+
     @property
     def error(self):
         if self.res_error:

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/lib/core/serviceproviders.py

@@ -97,6 +97,18 @@ class BaseProjectService(SuperannotateServiceProvider):
     def create(self, entity: entities.ProjectEntity) -> ProjectResponse:
         raise NotImplementedError
 
+    @abstractmethod
+    def attach_editor_template(
+        self, team: entities.TeamEntity, project: entities.ProjectEntity, template: dict
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_editor_template(
+        self, team: entities.TeamEntity, project: entities.ProjectEntity
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
     @abstractmethod
     def list(self, condition: Condition = None) -> ProjectListResponse:
         raise NotImplementedError
@@ -346,6 +358,7 @@ class BaseAnnotationService(SuperannotateServiceProvider):
         project: entities.ProjectEntity,
         item: entities.BaseItemEntity,
         reporter: Reporter,
+        transform_version: str = None,
     ) -> dict:
         raise NotImplementedError
 
@@ -357,6 +370,7 @@ class BaseAnnotationService(SuperannotateServiceProvider):
         item_ids: List[int],
         reporter: Reporter,
         callback: Callable = None,
+        transform_version: str = None,
     ) -> List[dict]:
         raise NotImplementedError
 
@@ -396,6 +410,7 @@ class BaseAnnotationService(SuperannotateServiceProvider):
         project: entities.ProjectEntity,
         folder: entities.FolderEntity,
         items_name_data_map: Dict[str, dict],
+        transform_version: str = None,
     ) -> UploadAnnotationsResponse:
         raise NotImplementedError
 
@@ -407,6 +422,7 @@ class BaseAnnotationService(SuperannotateServiceProvider):
         item_id: int,
         data: io.StringIO,
         chunk_size: int,
+        transform_version: str = None,
     ) -> bool:
         raise NotImplementedError
 
@@ -429,6 +445,29 @@ class BaseAnnotationService(SuperannotateServiceProvider):
     def get_schema(self, project_type: int, version: str) -> ServiceResponse:
         raise NotImplementedError
 
+    @abstractmethod
+    def get_item_annotations(
+        self,
+        project: entities.ProjectEntity,
+        folder: entities.FolderEntity,
+        item_id: int,
+        transform_version: str = "llmJsonV2",
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
+    @abstractmethod
+    def set_item_annotations(
+        self,
+        project: entities.ProjectEntity,
+        folder: entities.FolderEntity,
+        item_id: int,
+        data: dict,
+        overwrite: bool,
+        transform_version: str = "llmJsonV2",
+        etag: str = None,
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
 
 class BaseIntegrationService(SuperannotateServiceProvider):
     @abstractmethod

{superannotate-4.4.27 → superannotate-4.4.29.dev1}/src/superannotate/lib/core/usecases/annotations.py

@@ -9,12 +9,10 @@ import platform
 import re
 import time
 import traceback
-import typing
 from dataclasses import dataclass
 from itertools import islice
 from operator import itemgetter
 from pathlib import Path
-from threading import Thread
 from typing import Any
 from typing import Callable
 from typing import Dict
@@ -48,6 +46,7 @@ from lib.core.serviceproviders import ServiceResponse
 from lib.core.serviceproviders import UploadAnnotationsResponse
 from lib.core.types import PriorityScoreEntity
 from lib.core.usecases.base import BaseReportableUseCase
+from lib.core.utils import run_async
 from lib.core.video_convertor import VideoFrameGenerator
 from lib.infrastructure.utils import divide_to_chunks
 
@@ -66,51 +65,6 @@ ANNOTATION_CHUNK_SIZE_MB = 10 * 1024 * 1024
 URI_THRESHOLD = 4 * 1024 - 120
 
 
-class AsyncThread(Thread):
-    def __init__(
-        self, group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None
-    ):
-        super().__init__(
-            group=group,
-            target=target,
-            name=name,
-            args=args,
-            kwargs=kwargs,
-            daemon=daemon,
-        )
-        self._exc = None
-        self._response = None
-
-    @property
-    def response(self):
-        return self._response
-
-    def run(self):
-        try:
-            self._response = super().run()
-        except BaseException as e:
-            self._exc = e
-
-    def join(self, timeout=None) -> typing.Any:
-        Thread.join(self, timeout=timeout)
-        if self._exc:
-            raise self._exc
-        return self._response
-
-
-def run_async(f):
-    response = [None]
-
-    def wrapper(func: typing.Callable):
-        response[0] = asyncio.run(func)  # noqa
-        return response[0]
-
-    thread = AsyncThread(target=wrapper, args=(f,))
-    thread.start()
-    thread.join()
-    return response[0]
-
-
 @dataclass
 class Report:
     failed_annotations: list
@@ -188,6 +142,7 @@ async def upload_small_annotations(
     reporter: Reporter,
     report: Report,
     callback: Callable = None,
+    transform_version: str = None,
 ):
     async def upload(_chunk: List[ItemToUpload]):
         failed_annotations, missing_classes, missing_attr_groups, missing_attrs = (
@@ -204,6 +159,7 @@ async def upload_small_annotations(
                 project=project,
                 folder=folder,
                 items_name_data_map=items_name_data_map,
+                transform_version=transform_version,
             )
             if response.ok:
                 if response.data.failed_items:  # noqa
@@ -304,6 +260,7 @@ class UploadAnnotationsUseCase(BaseReportableUseCase):
         service_provider: BaseServiceProvider,
         user: UserEntity,
         keep_status: bool = False,
+        transform_version: str = None,
     ):
         super().__init__(reporter)
         self._project = project
@@ -313,6 +270,7 @@ class UploadAnnotationsUseCase(BaseReportableUseCase):
         self._keep_status = keep_status
         self._report = Report([], [], [], [])
         self._user = user
+        self._transform_version = transform_version
 
     def validate_project_type(self):
         if self._project.type == constants.ProjectType.PIXEL.value:
@@ -420,6 +378,7 @@ class UploadAnnotationsUseCase(BaseReportableUseCase):
                 service_provider=self._service_provider,
                 reporter=self.reporter,
                 report=self._report,
+                transform_version=self._transform_version,
             )
         )
 
@@ -1474,6 +1433,7 @@ class GetAnnotations(BaseReportableUseCase):
         service_provider: BaseServiceProvider,
         folder: FolderEntity = None,
         items: Optional[Union[List[str], List[int]]] = None,
+        transform_version: str = None,
     ):
         super().__init__(reporter)
         self._config = config
@@ -1484,6 +1444,7 @@ class GetAnnotations(BaseReportableUseCase):
         self._item_id_name_map = {}
         self._item_names_provided = True
         self._big_annotations_queue = None
+        self._transform_version = transform_version
 
     def validate_project_type(self):
         if self._project.type == constants.ProjectType.PIXEL.value:
@@ -1548,6 +1509,7 @@ class GetAnnotations(BaseReportableUseCase):
             folder=self._folder,
             item_ids=item_ids,
             reporter=self.reporter,
+            transform_version=self._transform_version,
         )
 
     async def run_workers(

superannotate-4.4.29.dev1/src/superannotate/lib/core/utils.py

@@ -0,0 +1,48 @@
+import asyncio
+import typing
+from threading import Thread
+
+
+class AsyncThread(Thread):
+    def __init__(
+        self, group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None
+    ):
+        super().__init__(
+            group=group,
+            target=target,
+            name=name,
+            args=args,
+            kwargs=kwargs,
+            daemon=daemon,
+        )
+        self._exc = None
+        self._response = None
+
+    @property
+    def response(self):
+        return self._response
+
+    def run(self):
+        try:
+            self._response = super().run()
+        except BaseException as e:
+            self._exc = e
+
+    def join(self, timeout=None) -> typing.Any:
+        Thread.join(self, timeout=timeout)
+        if self._exc:
+            raise self._exc
+        return self._response
+
+
+def run_async(f):
+    response = [None]
+
+    def wrapper(func: typing.Callable):
+        response[0] = asyncio.run(func)  # noqa
+        return response[0]
+
+    thread = AsyncThread(target=wrapper, args=(f,))
+    thread.start()
+    thread.join()
+    return response[0]