superannotate 4.4.26.dev1__tar.gz → 4.4.28__tar.gz

{superannotate-4.4.26.dev1/src/superannotate.egg-info → superannotate-4.4.28}/PKG-INFO

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

{superannotate-4.4.26.dev1 → superannotate-4.4.28}/src/superannotate/__init__.py

@@ -3,7 +3,7 @@ import os
 import sys
 
 
-__version__ = "4.4.26dev1"
+__version__ = "4.4.28"
 
 os.environ.update({"sa_version": __version__})
 sys.path.append(os.path.split(os.path.realpath(__file__))[0])
@@ -15,9 +15,10 @@ 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.app.input_converters import convert_project_type
-from lib.app.input_converters import export_annotation
-from lib.app.input_converters import import_annotation
+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
 from superannotate.lib.app.interface.sdk_interface import SAClient
 
 
@@ -30,6 +31,7 @@ __all__ = [
     # Utils
     "enums",
     "AppException",
+    "FileChangedError",
     "import_annotation",
     "export_annotation",
     "convert_project_type",

{superannotate-4.4.26.dev1 → superannotate-4.4.28}/src/superannotate/lib/app/interface/sdk_interface.py

@@ -28,11 +28,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 +47,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 +63,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 +74,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 +86,6 @@ PROJECT_TYPE = Literal[
     "Multimodal",
 ]
 
-
 APPROVAL_STATUS = Literal["Approved", "Disapproved", None]
 
 IMAGE_QUALITY = Literal["compressed", "original"]
@@ -110,6 +113,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
@@ -2556,19 +2640,13 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
             If recursive=False=True, then only the project name is required.
         :type project: str
 
-        :param name_contains:  Returns those items, where the given string is found anywhere within an item’s name.
+        :param name_contains:  returns those items, where the given string is found anywhere within an item’s name.
             If None, all items returned, in accordance with the recursive=False parameter.
         :type name_contains: str
 
-        :param annotation_status: if not None, filters items by annotation status. \n
-            Available statuses are::
+        :param annotation_status: returns items with the specified annotation status, which must match a predefined
+            status in the project workflow. If None, all items are returned.
 
-                     * NotStarted
-                     * InProgress
-                     * QualityCheck
-                     * Returned
-                     * Completed
-                     * Skipped
         :type annotation_status: str
 
         :param annotator_email: returns those items’ names that are assigned to the specified annotator.
@@ -3049,20 +3127,13 @@ class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
         annotation_status: NotEmptyStr,
         items: Optional[List[NotEmptyStr]] = None,
     ):
-        """Sets annotation statuses of items
+        """Sets annotation statuses of items.
 
         :param project: project name or folder path (e.g., “project1/folder1”).
         :type project: str
 
-        :param annotation_status: annotation status to set. \n
-            Available statuses are::
-
-                 * NotStarted
-                 * InProgress
-                 * QualityCheck
-                 * Returned
-                 * Completed
-                 * Skipped
+        :param annotation_status: The desired status to set for the annotation.
+            This status should match one of the predefined statuses available in the project workflow.
         :type annotation_status: str
 
         :param items:  item names. If None, all the items in the specified directory will be used.
@@ -3553,3 +3624,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.26.dev1 → superannotate-4.4.28}/src/superannotate/lib/core/__init__.py

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

{superannotate-4.4.26.dev1 → superannotate-4.4.28}/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.26.dev1 → superannotate-4.4.28}/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.26.dev1 → superannotate-4.4.28}/src/superannotate/lib/core/jsx_conditions.py

@@ -54,6 +54,18 @@ class Filter(Query):
         self._operator = operator
         self.condition_set = [self]
 
+    @property
+    def key(self) -> str:
+        return self._key
+
+    @property
+    def operator(self) -> OperatorEnum:
+        return self._operator
+
+    @property
+    def value(self) -> Any:
+        return self._value
+
     def _build(self):
         if isinstance(self._value, (list, set, tuple)):
             return f"{self._key}||{self._operator.value}||{','.join(map(urllib.parse.quote, map(str, self._value)))}"

{superannotate-4.4.26.dev1 → superannotate-4.4.28}/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.26.dev1 → superannotate-4.4.28}/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